From d2d14d5793999a94fa08f53a863ffef97e107fa4 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 19:52:26 -0400
Subject: [PATCH] docs: document plugin contract tests

---
 src/plugins/contracts/auth-choice.contract.test.ts               | 1 +
 src/plugins/contracts/boundary-invariants.test.ts                | 1 +
 .../contracts/bundled-extension-config-api-guardrails.test.ts    | 1 +
 src/plugins/contracts/config-boundary-guard.test.ts              | 1 +
 src/plugins/contracts/config-footprint-guardrails.test.ts        | 1 +
 src/plugins/contracts/core-extension-facade-boundary.test.ts     | 1 +
 src/plugins/contracts/deprecated-internal-config-api.test.ts     | 1 +
 src/plugins/contracts/embedding-provider.contract.test.ts        | 1 +
 .../contracts/extension-package-project-boundaries.test.ts       | 1 +
 .../contracts/extension-runtime-dependencies.contract.test.ts    | 1 +
 src/plugins/contracts/host-hook-fixture.ts                       | 1 +
 src/plugins/contracts/host-hooks.contract.test.ts                | 1 +
 src/plugins/contracts/inventory/bundled-capability-metadata.ts   | 1 +
 src/plugins/contracts/loader.contract.test.ts                    | 1 +
 src/plugins/contracts/memory-embedding-provider.contract.test.ts | 1 +
 src/plugins/contracts/model-catalog-core-imports.test.ts         | 1 +
 src/plugins/contracts/package-manifest.contract.test.ts          | 1 +
 src/plugins/contracts/plugin-entry-guardrails.test.ts            | 1 +
 src/plugins/contracts/plugin-registration.contract.test.ts       | 1 +
 src/plugins/contracts/plugin-sdk-index.bundle.test.ts            | 1 +
 src/plugins/contracts/plugin-sdk-index.test.ts                   | 1 +
 .../contracts/plugin-sdk-package-contract-guardrails.test.ts     | 1 +
 src/plugins/contracts/plugin-sdk-root-alias.test.ts              | 1 +
 src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts  | 1 +
 src/plugins/contracts/plugin-sdk-subpaths.test.ts                | 1 +
 src/plugins/contracts/plugin-tool-contracts.test.ts              | 1 +
 .../contracts/provider-catalog-deprecation.contract.test.ts      | 1 +
 src/plugins/contracts/provider-family-plugin-tests.test.ts       | 1 +
 src/plugins/contracts/providers.contract.test.ts                 | 1 +
 src/plugins/contracts/registry.contract.test.ts                  | 1 +
 src/plugins/contracts/registry.retry.test.ts                     | 1 +
 src/plugins/contracts/registry.ts                                | 1 +
 src/plugins/contracts/run-context-lifecycle.contract.test.ts     | 1 +
 .../contracts/runtime-import-side-effects.contract.test.ts       | 1 +
 src/plugins/contracts/runtime-seams.contract.test.ts             | 1 +
 src/plugins/contracts/scheduled-turns.contract.test.ts           | 1 +
 src/plugins/contracts/session-actions.contract.test.ts           | 1 +
 src/plugins/contracts/session-attachments.contract.test.ts       | 1 +
 src/plugins/contracts/session-entry-projection.contract.test.ts  | 1 +
 src/plugins/contracts/shape.contract.test.ts                     | 1 +
 src/plugins/contracts/speech-vitest-registry.ts                  | 1 +
 src/plugins/contracts/test-helpers/bundled-plugin-roots.ts       | 1 +
 src/plugins/contracts/tts-contract-suites.ts                     | 1 +
 src/plugins/contracts/tts.contract.test.ts                       | 1 +
 src/plugins/contracts/web-fetch-provider.contract.test.ts        | 1 +
 src/plugins/contracts/wizard.choice-resolution.contract.test.ts  | 1 +
 src/plugins/contracts/wizard.model-picker.contract.test.ts       | 1 +
 src/plugins/contracts/wizard.setup-options.contract.test.ts      | 1 +
 48 files changed, 48 insertions(+)

diff --git a/src/plugins/contracts/auth-choice.contract.test.ts b/src/plugins/contracts/auth-choice.contract.test.ts
index 84bb4f0a4775..52e5560d65ef 100644
--- a/src/plugins/contracts/auth-choice.contract.test.ts
+++ b/src/plugins/contracts/auth-choice.contract.test.ts
@@ -1,3 +1,4 @@
+// Auth choice contract tests cover provider auth choice metadata and setup behavior.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { clearRuntimeAuthProfileStoreSnapshots } from "../../agents/auth-profiles/store.js";
 import { resolvePreferredProviderForAuthChoice } from "../../plugins/provider-auth-choice-preference.js";
diff --git a/src/plugins/contracts/boundary-invariants.test.ts b/src/plugins/contracts/boundary-invariants.test.ts
index 0fac81cd5475..def8ea2a528c 100644
--- a/src/plugins/contracts/boundary-invariants.test.ts
+++ b/src/plugins/contracts/boundary-invariants.test.ts
@@ -1,3 +1,4 @@
+// Boundary invariant tests cover plugin boundary rules that must hold across the repo.
 import { spawnSync } from "node:child_process";
 import fs, { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
diff --git a/src/plugins/contracts/bundled-extension-config-api-guardrails.test.ts b/src/plugins/contracts/bundled-extension-config-api-guardrails.test.ts
index 1c49089b91bc..4a6a874632cd 100644
--- a/src/plugins/contracts/bundled-extension-config-api-guardrails.test.ts
+++ b/src/plugins/contracts/bundled-extension-config-api-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Bundled extension config API guardrail tests cover config API usage in bundled extensions.
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/config-boundary-guard.test.ts b/src/plugins/contracts/config-boundary-guard.test.ts
index 1892e836163d..4dc385638c2b 100644
--- a/src/plugins/contracts/config-boundary-guard.test.ts
+++ b/src/plugins/contracts/config-boundary-guard.test.ts
@@ -1,3 +1,4 @@
+// Config boundary guard tests cover plugin config ownership and forbidden core reads.
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
diff --git a/src/plugins/contracts/config-footprint-guardrails.test.ts b/src/plugins/contracts/config-footprint-guardrails.test.ts
index 556683e3a9b7..8bccfb818796 100644
--- a/src/plugins/contracts/config-footprint-guardrails.test.ts
+++ b/src/plugins/contracts/config-footprint-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Config footprint guardrail tests cover forbidden direct plugin config access patterns.
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/core-extension-facade-boundary.test.ts b/src/plugins/contracts/core-extension-facade-boundary.test.ts
index 83f9d8332a6e..5c28389d1718 100644
--- a/src/plugins/contracts/core-extension-facade-boundary.test.ts
+++ b/src/plugins/contracts/core-extension-facade-boundary.test.ts
@@ -1,3 +1,4 @@
+// Core extension facade boundary tests cover allowed imports between core and extension facades.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/deprecated-internal-config-api.test.ts b/src/plugins/contracts/deprecated-internal-config-api.test.ts
index c5d91e0b5b4e..a2e90a83a277 100644
--- a/src/plugins/contracts/deprecated-internal-config-api.test.ts
+++ b/src/plugins/contracts/deprecated-internal-config-api.test.ts
@@ -1,3 +1,4 @@
+// Deprecated internal config API tests cover forbidden legacy plugin config API usage.
 import { beforeAll, describe, expect, it } from "vitest";
 import { collectDeprecatedInternalConfigApiViolations } from "../../../scripts/lib/deprecated-config-api-guard.mjs";
 
diff --git a/src/plugins/contracts/embedding-provider.contract.test.ts b/src/plugins/contracts/embedding-provider.contract.test.ts
index ed98251357f4..4f086c7d7af4 100644
--- a/src/plugins/contracts/embedding-provider.contract.test.ts
+++ b/src/plugins/contracts/embedding-provider.contract.test.ts
@@ -1,3 +1,4 @@
+// Embedding provider contract tests cover plugin embedding provider SDK behavior.
 import * as embeddingProviderSdk from "openclaw/plugin-sdk/embedding-providers";
 import {
   createPluginRegistryFixture,
diff --git a/src/plugins/contracts/extension-package-project-boundaries.test.ts b/src/plugins/contracts/extension-package-project-boundaries.test.ts
index 770da5254902..fc4f71efd97f 100644
--- a/src/plugins/contracts/extension-package-project-boundaries.test.ts
+++ b/src/plugins/contracts/extension-package-project-boundaries.test.ts
@@ -1,3 +1,4 @@
+// Extension package boundary tests cover package/project boundaries for bundled extensions.
 import fs from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/plugins/contracts/extension-runtime-dependencies.contract.test.ts b/src/plugins/contracts/extension-runtime-dependencies.contract.test.ts
index 2528b74b7110..51796dcdf483 100644
--- a/src/plugins/contracts/extension-runtime-dependencies.contract.test.ts
+++ b/src/plugins/contracts/extension-runtime-dependencies.contract.test.ts
@@ -1,3 +1,4 @@
+// Extension runtime dependency contract tests cover runtime dependency placement for extensions.
 import fs from "node:fs";
 import { builtinModules } from "node:module";
 import path from "node:path";
diff --git a/src/plugins/contracts/host-hook-fixture.ts b/src/plugins/contracts/host-hook-fixture.ts
index ba0ac9c0f100..38d48f824af0 100644
--- a/src/plugins/contracts/host-hook-fixture.ts
+++ b/src/plugins/contracts/host-hook-fixture.ts
@@ -1,3 +1,4 @@
+// Host hook fixtures provide reusable plugin host-hook doubles for contract tests.
 import type { OpenClawPluginApi } from "../types.js";
 
 export function registerHostHookFixture(api: OpenClawPluginApi) {
diff --git a/src/plugins/contracts/host-hooks.contract.test.ts b/src/plugins/contracts/host-hooks.contract.test.ts
index 5e5e848397d5..cc8212b9b69c 100644
--- a/src/plugins/contracts/host-hooks.contract.test.ts
+++ b/src/plugins/contracts/host-hooks.contract.test.ts
@@ -1,3 +1,4 @@
+// Host hook contract tests cover plugin host hook registration and runtime behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
diff --git a/src/plugins/contracts/inventory/bundled-capability-metadata.ts b/src/plugins/contracts/inventory/bundled-capability-metadata.ts
index 0ded984d0edd..27d4b159b985 100644
--- a/src/plugins/contracts/inventory/bundled-capability-metadata.ts
+++ b/src/plugins/contracts/inventory/bundled-capability-metadata.ts
@@ -1,3 +1,4 @@
+// Bundled capability metadata inventory lists capability metadata used by plugin contracts.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/loader.contract.test.ts b/src/plugins/contracts/loader.contract.test.ts
index a64a7d4f8c6b..f1ae04ce314d 100644
--- a/src/plugins/contracts/loader.contract.test.ts
+++ b/src/plugins/contracts/loader.contract.test.ts
@@ -1,3 +1,4 @@
+// Loader contract tests cover plugin loader behavior, registry setup, and reset boundaries.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import { uniqueSortedStrings } from "../../plugin-sdk/test-helpers/string-utils.js";
 import { resolveManifestContractPluginIds } from "../plugin-registry.js";
diff --git a/src/plugins/contracts/memory-embedding-provider.contract.test.ts b/src/plugins/contracts/memory-embedding-provider.contract.test.ts
index 24e33c7f412c..7bcfb76224f1 100644
--- a/src/plugins/contracts/memory-embedding-provider.contract.test.ts
+++ b/src/plugins/contracts/memory-embedding-provider.contract.test.ts
@@ -1,3 +1,4 @@
+// Memory embedding provider contract tests cover memory plugin embedding provider behavior.
 import {
   createPluginRegistryFixture,
   registerVirtualTestPlugin,
diff --git a/src/plugins/contracts/model-catalog-core-imports.test.ts b/src/plugins/contracts/model-catalog-core-imports.test.ts
index 8e08e4e4053e..02847d1c0b49 100644
--- a/src/plugins/contracts/model-catalog-core-imports.test.ts
+++ b/src/plugins/contracts/model-catalog-core-imports.test.ts
@@ -1,3 +1,4 @@
+// Model catalog core import tests cover allowed model-catalog imports in plugin code.
 import fs from "node:fs";
 import path from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";
diff --git a/src/plugins/contracts/package-manifest.contract.test.ts b/src/plugins/contracts/package-manifest.contract.test.ts
index f15428da73bf..f309adafa9f0 100644
--- a/src/plugins/contracts/package-manifest.contract.test.ts
+++ b/src/plugins/contracts/package-manifest.contract.test.ts
@@ -1,3 +1,4 @@
+// Package manifest contract tests cover plugin package manifest requirements.
 import { describePackageManifestContract } from "openclaw/plugin-sdk/plugin-test-contracts";
 
 type PackageManifestContractParams = Parameters<typeof describePackageManifestContract>[0];
diff --git a/src/plugins/contracts/plugin-entry-guardrails.test.ts b/src/plugins/contracts/plugin-entry-guardrails.test.ts
index 9bdc94c2d74a..9268e0c5bbba 100644
--- a/src/plugins/contracts/plugin-entry-guardrails.test.ts
+++ b/src/plugins/contracts/plugin-entry-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Plugin entry guardrail tests cover allowed plugin entrypoint imports and exports.
 import { existsSync, readFileSync } from "node:fs";
 import path, { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/plugin-registration.contract.test.ts b/src/plugins/contracts/plugin-registration.contract.test.ts
index 61c81a7424fa..962460e7eb10 100644
--- a/src/plugins/contracts/plugin-registration.contract.test.ts
+++ b/src/plugins/contracts/plugin-registration.contract.test.ts
@@ -1,3 +1,4 @@
+// Plugin registration contract tests cover manifest registration cases exposed through the SDK.
 import { pluginRegistrationContractCases } from "openclaw/plugin-sdk/plugin-test-contracts";
 import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts";
 
diff --git a/src/plugins/contracts/plugin-sdk-index.bundle.test.ts b/src/plugins/contracts/plugin-sdk-index.bundle.test.ts
index d3ce2477de18..ed6f0f167567 100644
--- a/src/plugins/contracts/plugin-sdk-index.bundle.test.ts
+++ b/src/plugins/contracts/plugin-sdk-index.bundle.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK bundle index tests cover bundled SDK export inventory and packaging.
 import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
diff --git a/src/plugins/contracts/plugin-sdk-index.test.ts b/src/plugins/contracts/plugin-sdk-index.test.ts
index 61ded15b8708..39c33116bc39 100644
--- a/src/plugins/contracts/plugin-sdk-index.test.ts
+++ b/src/plugins/contracts/plugin-sdk-index.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK index tests cover SDK export baselines and public subpath availability.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts b/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts
index 7c1c8ad204d6..b92283eb03bf 100644
--- a/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts
+++ b/src/plugins/contracts/plugin-sdk-package-contract-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK package guardrail tests cover package export and contract drift checks.
 import fs from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/plugin-sdk-root-alias.test.ts b/src/plugins/contracts/plugin-sdk-root-alias.test.ts
index 5ee48b9f39c2..8cf0f4558bc0 100644
--- a/src/plugins/contracts/plugin-sdk-root-alias.test.ts
+++ b/src/plugins/contracts/plugin-sdk-root-alias.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK root alias tests cover package root alias compatibility for plugin authors.
 import fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
diff --git a/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts b/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
index 1b9accd5581d..de9a9e907736 100644
--- a/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
+++ b/src/plugins/contracts/plugin-sdk-runtime-api-guardrails.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK runtime API guardrail tests cover runtime API export safety and boundaries.
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/plugin-sdk-subpaths.test.ts b/src/plugins/contracts/plugin-sdk-subpaths.test.ts
index 4f472e75539d..b2d58e3ef31b 100644
--- a/src/plugins/contracts/plugin-sdk-subpaths.test.ts
+++ b/src/plugins/contracts/plugin-sdk-subpaths.test.ts
@@ -1,3 +1,4 @@
+// Plugin SDK subpath tests cover documented SDK subpath exports and package aliases.
 import fs, { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
diff --git a/src/plugins/contracts/plugin-tool-contracts.test.ts b/src/plugins/contracts/plugin-tool-contracts.test.ts
index 6995c461e24b..c048b105d048 100644
--- a/src/plugins/contracts/plugin-tool-contracts.test.ts
+++ b/src/plugins/contracts/plugin-tool-contracts.test.ts
@@ -1,3 +1,4 @@
+// Plugin tool contract tests cover bundled plugin tool schemas and invocation contracts.
 import fs from "node:fs";
 import path from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";
diff --git a/src/plugins/contracts/provider-catalog-deprecation.contract.test.ts b/src/plugins/contracts/provider-catalog-deprecation.contract.test.ts
index 2c71e5b14685..b570d19dd145 100644
--- a/src/plugins/contracts/provider-catalog-deprecation.contract.test.ts
+++ b/src/plugins/contracts/provider-catalog-deprecation.contract.test.ts
@@ -1,3 +1,4 @@
+// Provider catalog deprecation contract tests cover deprecated provider catalog metadata.
 import fs from "node:fs";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/plugins/contracts/provider-family-plugin-tests.test.ts b/src/plugins/contracts/provider-family-plugin-tests.test.ts
index d0c118fdb301..4ffd1ecf99be 100644
--- a/src/plugins/contracts/provider-family-plugin-tests.test.ts
+++ b/src/plugins/contracts/provider-family-plugin-tests.test.ts
@@ -1,3 +1,4 @@
+// Provider family plugin tests cover grouped provider-family contract cases.
 import fs from "node:fs";
 import { basename, resolve } from "node:path";
 import { beforeAll, describe, expect, it } from "vitest";
diff --git a/src/plugins/contracts/providers.contract.test.ts b/src/plugins/contracts/providers.contract.test.ts
index ae68f9f547c4..d529aaa865d5 100644
--- a/src/plugins/contracts/providers.contract.test.ts
+++ b/src/plugins/contracts/providers.contract.test.ts
@@ -1,3 +1,4 @@
+// Provider contract tests cover shared provider plugin behavior across bundled providers.
 import { describeProviderContracts } from "../../plugin-sdk/test-helpers/provider-contract.js";
 import { describeWebSearchProviderContracts } from "../../plugin-sdk/test-helpers/web-search-provider-contract.js";
 
diff --git a/src/plugins/contracts/registry.contract.test.ts b/src/plugins/contracts/registry.contract.test.ts
index 96f8742a8b97..4fecc6cbed72 100644
--- a/src/plugins/contracts/registry.contract.test.ts
+++ b/src/plugins/contracts/registry.contract.test.ts
@@ -1,3 +1,4 @@
+// Registry contract tests cover plugin contract registry contents and lookup behavior.
 import { describe, expect, it } from "vitest";
 import { uniqueSortedStrings } from "../../plugin-sdk/test-helpers/string-utils.js";
 import { loadPluginManifestRegistry, type PluginManifestRecord } from "../manifest-registry.js";
diff --git a/src/plugins/contracts/registry.retry.test.ts b/src/plugins/contracts/registry.retry.test.ts
index d6cd3dd000f0..bf16e8d1f219 100644
--- a/src/plugins/contracts/registry.retry.test.ts
+++ b/src/plugins/contracts/registry.retry.test.ts
@@ -1,3 +1,4 @@
+// Registry retry tests cover plugin registry retry behavior after transient failures.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { ProviderPlugin, WebFetchProviderPlugin, WebSearchProviderPlugin } from "../types.js";
 
diff --git a/src/plugins/contracts/registry.ts b/src/plugins/contracts/registry.ts
index f8f0a9626f55..364bcfc25539 100644
--- a/src/plugins/contracts/registry.ts
+++ b/src/plugins/contracts/registry.ts
@@ -1,3 +1,4 @@
+// Plugin contract registry assembles bundled plugin fixtures for shared contract tests.
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { loadBundledCapabilityRuntimeRegistry } from "../bundled-capability-runtime.js";
diff --git a/src/plugins/contracts/run-context-lifecycle.contract.test.ts b/src/plugins/contracts/run-context-lifecycle.contract.test.ts
index 3cda39be3969..7f412f74e630 100644
--- a/src/plugins/contracts/run-context-lifecycle.contract.test.ts
+++ b/src/plugins/contracts/run-context-lifecycle.contract.test.ts
@@ -1,3 +1,4 @@
+// Run context lifecycle contract tests cover plugin run context setup and cleanup.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
diff --git a/src/plugins/contracts/runtime-import-side-effects.contract.test.ts b/src/plugins/contracts/runtime-import-side-effects.contract.test.ts
index 745bb37bd8f7..46e9934932c1 100644
--- a/src/plugins/contracts/runtime-import-side-effects.contract.test.ts
+++ b/src/plugins/contracts/runtime-import-side-effects.contract.test.ts
@@ -1,3 +1,4 @@
+// Runtime import side-effect contract tests cover cold import behavior for plugin runtime code.
 import fs from "node:fs";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { assertNoImportTimeSideEffects } from "../../plugin-sdk/test-helpers/import-side-effects.js";
diff --git a/src/plugins/contracts/runtime-seams.contract.test.ts b/src/plugins/contracts/runtime-seams.contract.test.ts
index 21cf1a306cd8..4805825f2608 100644
--- a/src/plugins/contracts/runtime-seams.contract.test.ts
+++ b/src/plugins/contracts/runtime-seams.contract.test.ts
@@ -1,3 +1,4 @@
+// Runtime seam contract tests cover allowed plugin runtime entrypoints and import boundaries.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/plugins/contracts/scheduled-turns.contract.test.ts b/src/plugins/contracts/scheduled-turns.contract.test.ts
index 952d9a2e4f82..457a89907494 100644
--- a/src/plugins/contracts/scheduled-turns.contract.test.ts
+++ b/src/plugins/contracts/scheduled-turns.contract.test.ts
@@ -1,3 +1,4 @@
+// Scheduled turn contract tests cover plugin scheduled turn metadata and timestamp bounds.
 import { MAX_DATE_TIMESTAMP_MS } from "@openclaw/normalization-core/number-coercion";
 import {
   createPluginRegistryFixture,
diff --git a/src/plugins/contracts/session-actions.contract.test.ts b/src/plugins/contracts/session-actions.contract.test.ts
index 50df9a03a2a0..b47cc4378494 100644
--- a/src/plugins/contracts/session-actions.contract.test.ts
+++ b/src/plugins/contracts/session-actions.contract.test.ts
@@ -1,3 +1,4 @@
+// Session action contract tests cover plugin session action metadata and execution contracts.
 import {
   createPluginRegistryFixture,
   registerTestPlugin,
diff --git a/src/plugins/contracts/session-attachments.contract.test.ts b/src/plugins/contracts/session-attachments.contract.test.ts
index 3539b7aeec6b..8bf1f01a392a 100644
--- a/src/plugins/contracts/session-attachments.contract.test.ts
+++ b/src/plugins/contracts/session-attachments.contract.test.ts
@@ -1,3 +1,4 @@
+// Session attachment contract tests cover plugin session attachment metadata and storage.
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { FILE_TYPE_SNIFF_MAX_BYTES } from "@openclaw/media-core/mime";
diff --git a/src/plugins/contracts/session-entry-projection.contract.test.ts b/src/plugins/contracts/session-entry-projection.contract.test.ts
index 3935014ab395..c7ab5244f8a4 100644
--- a/src/plugins/contracts/session-entry-projection.contract.test.ts
+++ b/src/plugins/contracts/session-entry-projection.contract.test.ts
@@ -1,3 +1,4 @@
+// Session entry projection contract tests cover plugin session entry projection behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import {
diff --git a/src/plugins/contracts/shape.contract.test.ts b/src/plugins/contracts/shape.contract.test.ts
index 9ac0fb36c20a..92c54234a61a 100644
--- a/src/plugins/contracts/shape.contract.test.ts
+++ b/src/plugins/contracts/shape.contract.test.ts
@@ -1,3 +1,4 @@
+// Plugin shape contract tests cover manifest, API, and runtime export shapes.
 import {
   createPluginRegistryFixture,
   registerVirtualTestPlugin,
diff --git a/src/plugins/contracts/speech-vitest-registry.ts b/src/plugins/contracts/speech-vitest-registry.ts
index 9d2f6717d690..5954f54c66a2 100644
--- a/src/plugins/contracts/speech-vitest-registry.ts
+++ b/src/plugins/contracts/speech-vitest-registry.ts
@@ -1,3 +1,4 @@
+// Speech Vitest registry helpers load speech capability runtimes for contract tests.
 import { loadBundledCapabilityRuntimeRegistry } from "../bundled-capability-runtime.js";
 import type {
   ImageGenerationProviderPlugin,
diff --git a/src/plugins/contracts/test-helpers/bundled-plugin-roots.ts b/src/plugins/contracts/test-helpers/bundled-plugin-roots.ts
index 2a6b22d1f4df..c3374ebae8c7 100644
--- a/src/plugins/contracts/test-helpers/bundled-plugin-roots.ts
+++ b/src/plugins/contracts/test-helpers/bundled-plugin-roots.ts
@@ -1,3 +1,4 @@
+// Bundled plugin root helpers resolve plugin root paths for contract test fixtures.
 import { relative, resolve } from "node:path";
 import { loadPluginManifestRegistry } from "../../manifest-registry.js";
 
diff --git a/src/plugins/contracts/tts-contract-suites.ts b/src/plugins/contracts/tts-contract-suites.ts
index 29808358e854..87fc29ada877 100644
--- a/src/plugins/contracts/tts-contract-suites.ts
+++ b/src/plugins/contracts/tts-contract-suites.ts
@@ -1,3 +1,4 @@
+// TTS contract suites provide reusable text-to-speech plugin contract assertions.
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import {
   createEmptyPluginRegistry,
diff --git a/src/plugins/contracts/tts.contract.test.ts b/src/plugins/contracts/tts.contract.test.ts
index 9d935390af28..3078a3f4e1f3 100644
--- a/src/plugins/contracts/tts.contract.test.ts
+++ b/src/plugins/contracts/tts.contract.test.ts
@@ -1,3 +1,4 @@
+// TTS contract tests cover text-to-speech plugin capability and runtime behavior.
 import {
   describeTtsAutoApplyContract,
   describeTtsConfigContract,
diff --git a/src/plugins/contracts/web-fetch-provider.contract.test.ts b/src/plugins/contracts/web-fetch-provider.contract.test.ts
index 116cb93f9397..b9d637526ba8 100644
--- a/src/plugins/contracts/web-fetch-provider.contract.test.ts
+++ b/src/plugins/contracts/web-fetch-provider.contract.test.ts
@@ -1,3 +1,4 @@
+// Web fetch provider contract tests cover plugin web-fetch provider behavior.
 import { describeWebFetchProviderContracts } from "../../plugin-sdk/test-helpers/web-fetch-provider-contract.js";
 import { pluginRegistrationContractRegistry } from "./registry.js";
 
diff --git a/src/plugins/contracts/wizard.choice-resolution.contract.test.ts b/src/plugins/contracts/wizard.choice-resolution.contract.test.ts
index f58dbf4b9a1e..298c9312eada 100644
--- a/src/plugins/contracts/wizard.choice-resolution.contract.test.ts
+++ b/src/plugins/contracts/wizard.choice-resolution.contract.test.ts
@@ -1,3 +1,4 @@
+// Wizard choice resolution contract tests cover provider setup choice matching.
 import { describeProviderWizardChoiceResolutionContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardChoiceResolutionContract();
diff --git a/src/plugins/contracts/wizard.model-picker.contract.test.ts b/src/plugins/contracts/wizard.model-picker.contract.test.ts
index c9af32bebd77..ca1c32ec0dc6 100644
--- a/src/plugins/contracts/wizard.model-picker.contract.test.ts
+++ b/src/plugins/contracts/wizard.model-picker.contract.test.ts
@@ -1,3 +1,4 @@
+// Wizard model picker contract tests cover provider setup wizard model selection.
 import { describeProviderWizardModelPickerContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardModelPickerContract();
diff --git a/src/plugins/contracts/wizard.setup-options.contract.test.ts b/src/plugins/contracts/wizard.setup-options.contract.test.ts
index b09e371e76a2..ae5d91a11441 100644
--- a/src/plugins/contracts/wizard.setup-options.contract.test.ts
+++ b/src/plugins/contracts/wizard.setup-options.contract.test.ts
@@ -1,3 +1,4 @@
+// Wizard setup option contract tests cover provider setup option metadata.
 import { describeProviderWizardSetupOptionsContract } from "openclaw/plugin-sdk/provider-test-contracts";
 
 describeProviderWizardSetupOptionsContract();