@unbrained/pm-cli 2026.6.20 → 2026.6.22

package/docs/COMMANDS.md

@@ -618,6 +618,8 @@ pm validate --check-metadata --json | jq -r '.checks[] | select(.name=="metadata
 
 `pm validate --check-files` classifies every stale linked path in `details.missing_linked_path_classifications` as either `moved` (a file with the same basename still exists in the scan — the row carries the top relink candidate, e.g. `old/path.md:moved:new/path.md`) or `deleted` (no candidate anywhere, e.g. `old/path.md:deleted`). It also reports `details.missing_linked_path_rows` — owner attribution so cleanup is evidence-based without a reverse lookup. By default these are token-efficient one-liners (`<path>:<classification> owner=<id> status=<status> field=<files|docs> title="…"`); `--verbose-file-lists` expands them to the full structured shape (`{ path, classification, items: [{ id, type, title, status, field }] }`). Orphaned existing files get the same treatment through `details.orphaned_path_classifications` and `details.orphaned_path_rows`; classifications start with `docs_unowned`, `tests_unowned`, `source_unowned`, or `unlinked_existing`, and rows include a concrete `pm docs|files <id> --add ...` hint when a likely owner is found from nearby linked paths. `--prune-missing` bulk-removes the stale links classified `deleted` from their items (link removal only — real files are never touched; `moved` links are kept so their relink candidates are not lost) and reports each removal in `fixes.applied_fixes[]` as the equivalent `pm files <id> --remove <path>` / `pm docs <id> --remove <path>` command. It honors `--dry-run` and implies `--check-files`.
 
+The default `pm validate` run also includes a `format_version` check that compares every item's stored front-matter format version (`pm_format_version`, absent meaning the implicit baseline version `1`) against the version this pm runtime writes. `details.outdated_items` lists items that predate the current version (a future storage migration would rewrite them — advisory `warn`); `details.ahead_items` lists items written by a *newer* pm than the one running, which is an `error` because validation cannot vouch for fields it does not understand (upgrade pm to read them safely). At the current baseline version both lists are empty and the check is `ok`. The same `pm_format_version` integrity is surfaced by `pm health` under the `integrity` check (`details.counts.item_outdated_format_version` / `item_ahead_format_version`).
+
 ### Telemetry Local Analytics
 
 `pm telemetry` surfaces local queue/runtime telemetry state without running full health checks:

package/docs/EXTENSIONS.md

@@ -4,6 +4,7 @@ Packages add optional `pm` workflows without changing the core CLI. A package ca
 
 ```bash
 pm package init ./my-package
+pm package init ./my-hook-package --capability hooks
 pm install ./my-package --project
 pm package doctor --project --detail summary
 pm package reload --project
@@ -86,7 +87,7 @@ Package roots declare resources in `package.json` under `pm`:
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
 
-`pm package init` emits a root extension (`"extensions": ["."]`) so local package installs can activate without dependency bootstrapping. Larger packages may point at nested extension directories after declaring runtime dependencies and validating with `pm package doctor`.
+`pm package init` emits a root extension (`"extensions": ["."]`) so local package installs can activate without dependency bootstrapping. The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`.
 
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
@@ -198,7 +199,7 @@ Rules:
 - Both bounds share the same warning-code shapes: `*_invalid` blocks, `*_unchecked` allows with a warning, and `extension_pm_min_version_unmet` / `extension_pm_max_version_exceeded` blocks unless the max-version warn mode is enabled.
 - An empty-string or non-string `pm_min_version`/`pm_max_version` makes the whole manifest malformed (`extension_manifest_invalid:<layer>:<name>`). Omit the field instead of leaving it blank.
 - Optional `engines.pm` and `engines.node` metadata is accepted for tooling, but `pm_min_version`/`pm_max_version` are the loader-enforced compatibility fields.
-- Declare only capabilities the extension actually uses.
+- Declare only capabilities the extension actually uses. Declaring a capability it never registers against is over-broad: `pm package doctor` emits an advisory `extension_capability_unused:<layer>:<name>:<capability>` warning (never blocking) so you can trim the manifest, while the inverse — registering a surface whose capability is undeclared — is the blocking `extension_capability_missing` activation failure. Catch over-declaration earlier with the `assertExtensionCapabilityUsage` SDK testing helper.
 - Unknown capabilities emit deterministic warnings.
 - Legacy aliases such as `migration` and `validation` are normalized to `schema` with warnings.
 
@@ -420,12 +421,7 @@ import { activateExtensionForTest, assertRegisteredCommandContract } from "@unbr
 
 Use `createPmCliExpectedError(message, { exitCode, context })` for expected user/action failures from package commands. It creates an `Error` named `PmCliError` with a structural `exitCode`, so separately installed package code still gets expected-error handling and Sentry filtering.
 
-Use `activateExtensionForTest(module)` in package unit tests when you need an
-`activation.registrations` or `activation.hooks` object for assertion helpers.
-It exercises the real activation and capability validation path without
-requiring private loader imports or a temporary `.agents/pm/extensions` tree.
-Keep `pm package doctor --project --detail deep --trace` and runtime contracts
-for integration tests against installed packages.
+Use `activateExtensionForTest(module)` in package unit tests when you need an `activation.registrations` or `activation.hooks` object for assertion helpers. Then `runRegisteredCommandForTest(activation.commands, { command })` invokes a registered command handler through pm's real dispatch engine to assert behavior, not just wiring; the matching `runRegisteredHookForTest` (lifecycle hooks), `runRegistered{Parser,Preflight,Command,Renderer,Service}OverrideForTest` (override surfaces), and `runRegistered{SearchProvider,VectorStoreAdapter,Migration,Importer,Exporter}ForTest` (executable registrations — the importer/exporter helpers take the whole `activation` and resolve by name, deriving the command path internally) helpers extend that invoke verb to every other runtime surface. Keep `pm package doctor --project --detail deep --trace` and runtime contracts for integration tests against installed packages.
 
 `PM_CLI_PACKAGE_ROOT` is first-party only. Bundled packages in this repository use it to find the running CLI's `dist/sdk/runtime.js` before they are published or installed independently. External packages must not read this environment variable or import from `dist/` or `src/core`; use `@unbrained/pm-cli/sdk`, `@unbrained/pm-cli/sdk/runtime`, and `@unbrained/pm-cli/sdk/testing`. During `pm install npm:<package>`, pm links the installed package's `@unbrained/pm-cli` dependency back to the running host CLI so SDK imports resolve without a duplicate nested CLI install.
 

package/docs/SDK.md

@@ -55,6 +55,14 @@ Package manifest exports:
 - `readPmPackageManifest`
 - `collectPackageExtensionDirectories`
 
+Storage format-version exports (under `@unbrained/pm-cli/sdk/runtime`):
+
+- `CURRENT_ITEM_FORMAT_VERSION` / `BASELINE_ITEM_FORMAT_VERSION`
+- `effectiveItemFormatVersion` (resolve an item's stored version; absent means the baseline)
+- `normalizeItemFormatVersion` (persisted form; the baseline is dropped so it is never serialized)
+- `classifyItemFormatVersion` (`current` / `outdated` / `ahead`)
+- `scanItemFormatVersions` (partition items into outdated/ahead reference lists)
+
 Command/action contract exports:
 
 - `PM_CORE_COMMAND_NAMES`
@@ -66,8 +74,23 @@ Command/action contract exports:
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
 - `activateExtensionForTest`
+- `deactivateExtensionForTest`
+- `runRegisteredCommandForTest`
+- `runRegisteredHookForTest`
+- `runRegisteredParserOverrideForTest`
+- `runRegisteredPreflightOverrideForTest`
+- `runRegisteredCommandOverrideForTest`
+- `runRegisteredRendererOverrideForTest`
+- `runRegisteredServiceOverrideForTest`
+- `runRegisteredSearchProviderForTest`
+- `runRegisteredVectorStoreAdapterForTest`
+- `runRegisteredMigrationForTest`
+- `runRegisteredImporterForTest`
+- `runRegisteredExporterForTest`
+- `assertExtensionDeactivated`
 - `assertPackageManifest`
 - `assertRegisteredCommandContract`
+- `assertRegisteredFlags`
 - `assertRegisteredCommandOverride`
 - `assertRegisteredParserOverride`
 - `assertRegisteredPreflightOverride`
@@ -77,6 +100,113 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredImporter`
 - `assertRegisteredExporter`
 - `assertRegisteredVectorStoreAdapter`
+- `assertRegisteredItemField`
+- `assertRegisteredItemType`
+- `assertRegisteredServiceOverride`
+- `assertRegisteredMigration`
+- `assertExtensionCapabilityUsage`
+
+`assertExtensionCapabilityUsage(activation, { declared })` is the least-privilege
+counterpart of the per-surface `assertRegistered*` helpers: pass the same
+capabilities as your `manifest.capabilities` and it fails the test when the
+manifest grants a capability the extension never registers against. Use
+`allowUnused` for capabilities a runtime registers only behind a config flag.
+
+`deactivateExtensionForTest(module, options)` is the teardown counterpart to
+`activateExtensionForTest`: it runs pm's real `deactivateExtensions` engine
+(including the bounded per-hook timeout and best-effort failure capture) over the
+module and returns the `ExtensionDeactivationResult`, so a package can prove its
+`deactivate` releases the resources `activate` opened. `assertExtensionDeactivated(result)`
+asserts the single-extension happy path (one extension deactivated, none failed)
+by default; pass `{ deactivated, failed }` to assert other counts. Forward the
+`activation` result and `deactivateTimeoutMs` to mirror real host teardown.
+
+`runRegisteredCommandForTest(activation.commands, { command, args, options, global, pmRoot })`
+is the "invoke" verb that completes the package-author testing loop —
+`activateExtensionForTest` → `assertRegisteredCommandContract` → **run** →
+`deactivateExtensionForTest`. It dispatches a registered command handler through
+pm's real engine and returns the `CommandHandlerResult`, so a test can assert
+*behavior* (`result.result`) rather than only that the command is wired. The
+`CommandHandlerContext` is built with agent-safe global defaults
+(`{ json: true, quiet: true, noPager: true }`) that callers may override. A clean
+run yields `{ handled: true, result, warnings: [] }`; a handler that throws a
+non-exit error yields `{ handled: false, warnings: [code], errorMessage }` so the
+failure can be asserted, while one that throws an error carrying a numeric
+`exitCode` propagates the throw. An unregistered command throws a descriptive
+error listing the available handler command paths. Because
+`registerImporter`/`registerExporter` register handlers under `"<name> import"` /
+`"<name> export"`, the same helper exercises importer and exporter handlers too.
+
+The remaining runtime surfaces an extension can register have matching invoke
+helpers, so the "invoke" verb covers the whole command pipeline — not just
+command handlers:
+
+- `runRegisteredHookForTest(activation.hooks, { kind, context })` fires every
+  registered lifecycle hook of a `kind` (`before_command` | `after_command` |
+  `on_read` | `on_write` | `on_index`) through pm's real hook runner and returns
+  the warnings array (`[]` = clean; a thrown hook contributes one
+  `extension_hook_failed:*` warning while the others still run). The `context` is
+  type-safe per `kind`.
+- `runRegisteredParserOverrideForTest(activation.parsers, context)` returns the
+  rewritten `ParserOverrideResult` (args/options/global the override produces
+  before dispatch).
+- `runRegisteredPreflightOverrideForTest(activation.preflight, context)` returns
+  the `PreflightOverrideResult` (the migration/format gate decision).
+- `runRegisteredCommandOverrideForTest(activation.commands, context)` returns the
+  `CommandOverrideResult` (the transformed command result payload).
+- `runRegisteredRendererOverrideForTest(activation.renderers, context)` returns
+  the `RendererOverrideResult` (the custom string rendered for an output format).
+- `runRegisteredServiceOverrideForTest(activation.services, context)` returns the
+  `ServiceOverrideResult` (how the override handles an internal service payload).
+
+Each override helper guards that a matching override is registered for the target
+(command / format / service), so a typo surfaces as a descriptive error rather
+than a silent `overridden: false` / `handled: false`.
+
+The *executable registration* surfaces — search providers, vector store
+adapters, schema migrations, importers, and exporters — also have invoke helpers,
+so every executable register\* method has both an `assertRegistered*` and a
+`runRegistered*ForTest` counterpart. Each exercises the real registered behavior,
+not a re-implementation, but along two execution paths that mirror how the host
+runs them. Providers, adapters, and migrations are resolved through the same
+runtime resolver the host uses and invoked via their `runtime_definition` (the
+clone that preserves live functions). Importers and exporters have no standalone
+`runtime_definition` — `registerImporter`/`registerExporter` wrap their handler
+into a command path, so their helpers resolve by name and dispatch through the
+command runner instead, returning a `CommandHandlerResult`:
+
+- `runRegisteredSearchProviderForTest(activation.registrations, { provider, operation, context })`
+  resolves a registered provider by name (case-insensitive, last registration
+  wins) and invokes one `operation` — `query`, `embed`, `embedBatch`,
+  `queryExpansion`, or `rerank` — returning that operation's result. The
+  `context` and return type are inferred from `operation`, and the camelCase /
+  snake_case spellings the host accepts (`embedBatch`/`embed_batch`,
+  `queryExpansion`/`query_expansion`) both resolve.
+- `runRegisteredVectorStoreAdapterForTest(activation.registrations, { adapter, operation, context })`
+  resolves a registered adapter by name and invokes `query` (returns
+  `VectorStoreQueryHit[]`), `upsert`, or `delete`.
+- `runRegisteredMigrationForTest(activation.registrations, { migration, extensionName?, pmRoot? })`
+  resolves a registered migration by id and invokes its `run` with a context
+  mirroring the host's (`command: "migration"`, the registering extension's
+  layer/name, the supplied `pmRoot`, and the migration's normalized status),
+  returning whatever `run` returns. Unlike the host — which skips applied
+  migrations and folds a throw into a warning — it always invokes `run` and lets a
+  throw propagate, so both success and failure are assertable.
+- `runRegisteredImporterForTest(activation, { importer, extensionName?, args?, options?, global?, pmRoot? })`
+  and `runRegisteredExporterForTest(activation, { exporter, ... })` resolve a
+  registered importer/exporter by name, derive the `"<name> import"` /
+  `"<name> export"` command path internally — so authors never hand-build it — and
+  validate that the name is genuinely a registered importer/exporter before
+  dispatching. They take the whole `activation` because resolution spans two
+  sub-registries (`registrations` proves it exists, `commands` holds the wrapped
+  handler), and they return the command runner's `CommandHandlerResult` verbatim,
+  so `handled`/`warnings`/`errorMessage` semantics and `exitCode` propagation match
+  invoking the importer/exporter as a command.
+
+Each surface helper guards that the named provider / adapter / migration /
+importer / exporter is registered (and, for providers and adapters, implements the
+requested operation), so a typo surfaces as a descriptive error rather than a
+silent no-op. All invoke helpers are `async`, so a test always `await`s them.
 
 Commander option contract exports:
 
@@ -103,6 +233,13 @@ Extension runtime contract exports:
 - `PM_EXTENSION_TRUST_MODE_CONTRACTS`
 - `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
 
+Least-privilege capability reconciliation exports (map declared capabilities to
+the registration surfaces a package actually exercises at activation):
+
+- `EXTENSION_CAPABILITY_REGISTRATION_SURFACES`
+- `collectUsedExtensionCapabilities`
+- `reconcileExtensionCapabilityUsage`
+
 Common types:
 
 - `ExtensionApi`
@@ -182,6 +319,29 @@ assertPackageManifest(manifest, {
 });
 ```
 
+Package tests can also assert extension registrations without importing private
+loader internals. Use `activateExtensionForTest` plus the targeted assertion for
+the surface your package owns:
+
+```ts
+import {
+  activateExtensionForTest,
+  assertRegisteredCommandContract,
+  assertRegisteredFlags,
+} from "@unbrained/pm-cli/sdk/testing";
+
+const activation = await activateExtensionForTest(extensionModule);
+
+assertRegisteredCommandContract(activation.registrations, {
+  command: "incident triage",
+  flags: ["--severity"],
+});
+assertRegisteredFlags(activation.registrations, {
+  targetCommand: "list",
+  flags: ["--incident-filter"],
+});
+```
+
 For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat and avoids advanced schema constructs such as root `oneOf`.
 
 ## Capability Requirements
@@ -246,6 +406,16 @@ Manifest:
   "version": "0.1.0",
   "entry": "./index.js",
   "pm_min_version": "2026.5.31",
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": false,
+    "fs_write": false,
+    "network": false,
+    "env_read": false,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands"]
 }
 ```
@@ -264,11 +434,27 @@ Manifest typing also accepts optional `engines` metadata:
 ```
 
 Use `pm_min_version` for the loader gate. Keep `engines` as package-manager and tooling metadata.
+For pure command packages, keep `trusted: true`, `sandbox_profile: "strict"`, and all six permissions set to `false`; relax only the permission keys the package actually needs and verify the result with `pm package doctor --project --detail deep --trace`.
 
 For a complete commands-capability package that combines `registerCommand`,
 `registerFlags`, and `registerParser`, see the first-party
 [pm-command-kit exemplar](../packages/pm-command-kit/README.md).
 
+For a generated starter, use `pm package init ./my-package`. Pass
+`--capability hooks` to scaffold a command plus an `afterCommand` lifecycle
+reactor and a runnable `node:test` file that exercises
+`activateExtensionForTest`, `assertRegisteredHook`, `runRegisteredHookForTest`,
+and `deactivateExtensionForTest`. Pass `--capability search` to scaffold a
+command plus a deterministic search provider/vector-store adapter pair and a
+runnable `node:test` file that exercises `assertRegisteredSearchProvider`,
+`assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and
+`runRegisteredVectorStoreAdapterForTest`. Pass `--capability importers` to
+scaffold paired import/export commands with example flag metadata and a runnable
+`node:test` file that exercises `assertRegisteredImporter`,
+`assertRegisteredExporter`, `runRegisteredImporterForTest`, and
+`runRegisteredExporterForTest`; the generated manifest declares both `importers`
+and `schema` because extension flag metadata is schema-governed.
+
 ## Self-Identity and Lifecycle
 
 `activate(api)` receives a read-only `api.extension` describing the extension it
@@ -421,6 +607,80 @@ guardrails, but it does not discover files or install packages. Use it for unit
 tests of extension registration shape; keep `pm package doctor` and runtime
 contracts in integration tests.
 
+Invoke a registered command handler to assert its behavior (not just that it was
+registered). `runRegisteredCommandForTest` dispatches through pm's real engine and
+returns the `CommandHandlerResult`:
+
+```ts
+import { runRegisteredCommandForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const invocation = await runRegisteredCommandForTest(activation.commands, {
+  command: "hello",
+  options: { name: "ada" },
+});
+
+// invocation.handled === true; invocation.result is the handler's return value.
+```
+
+Importers and exporters get dedicated name-based helpers so tests never hand-build
+the `"<name> import"` / `"<name> export"` command path. Pass the whole `activation`
+and the registration name:
+
+```ts
+import { runRegisteredImporterForTest, runRegisteredExporterForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const imported = await runRegisteredImporterForTest(activation, {
+  importer: "csv",
+  options: { rows: 3 },
+});
+const exported = await runRegisteredExporterForTest(activation, { exporter: "csv" });
+
+// Both return a CommandHandlerResult: imported.result is the importer's return value.
+```
+
+Fire a registered lifecycle hook to assert its behavior (the `context` is
+type-safe per `kind`). A clean run returns `[]`; a hook that throws contributes a
+single `extension_hook_failed:*` warning while the others still run:
+
+```ts
+import { runRegisteredHookForTest } from "@unbrained/pm-cli/sdk/testing";
+
+const warnings = await runRegisteredHookForTest(activation.hooks, {
+  kind: "after_command",
+  context: { command: "close", args: ["pm-1a2b"], pm_root: "", ok: true },
+});
+// warnings === [] when every after_command hook ran cleanly.
+```
+
+The override surfaces have parallel invoke helpers that delegate to pm's real
+runners and return the override result verbatim, after guarding that a matching
+override is registered for the target (command / format / service):
+
+```ts
+import {
+  runRegisteredParserOverrideForTest,
+  runRegisteredCommandOverrideForTest,
+  runRegisteredRendererOverrideForTest,
+  runRegisteredServiceOverrideForTest,
+  runRegisteredPreflightOverrideForTest,
+} from "@unbrained/pm-cli/sdk/testing";
+
+const parsed = await runRegisteredParserOverrideForTest(activation.parsers, {
+  command: "deploy",
+  args: ["staging"],
+  options: {},
+  global: {},
+  pm_root: "",
+});
+// parsed.overridden === true; parsed.context holds the rewritten args/options.
+
+const rendered = await runRegisteredRendererOverrideForTest(activation.renderers, {
+  format: "toon",
+  result: { id: "pm-1a2b" },
+});
+// rendered.rendered is the custom string the override produced.
+```
+
 Assert a command registration contract:
 
 ```ts
@@ -514,6 +774,74 @@ assertRegisteredPreflightOverride(activation.preflight); // preflight overrides
 assertRegisteredRendererOverride(activation.renderers, { format: "toon" });
 ```
 
+Service overrides from `registerService(service, override)` live on
+`activation.services` (an `ExtensionServiceRegistry`), so
+`assertRegisteredServiceOverride` takes the service registry and a known service
+name (`output_format` | `error_format` | `help_format` | `lock_acquire` |
+`lock_release` | `history_append` | `item_store_write` | `item_store_delete`):
+
+```ts
+import { assertRegisteredServiceOverride } from "@unbrained/pm-cli/sdk/testing";
+
+const service = assertRegisteredServiceOverride(activation.services, {
+  service: "output_format",
+  extensionName: "my-ext",
+});
+// service.run is the registered ServiceOverride handler
+```
+
+Schema migrations from `registerMigration(definition)` live on
+`activation.registrations.migrations`. `assertRegisteredMigration` matches by the
+migration `id` and can additionally assert the `mandatory` governance flag (an
+unset flag is treated as non-mandatory):
+
+```ts
+import { assertRegisteredMigration } from "@unbrained/pm-cli/sdk/testing";
+
+const migration = assertRegisteredMigration(activation.registrations, {
+  migration: "backfill-severity",
+  mandatory: true,
+});
+// migration.definition is the normalized SchemaMigrationDefinition
+```
+
+Together these complete the SDK assertion surface: every extension `register*`
+method now has a matching `assertRegistered*` helper, so packages can prove any
+registration without importing private registry internals.
+
+The three executable registration surfaces add `runRegistered*ForTest` invoke
+helpers on top of those assertions, so a package can exercise the real behavior of
+a custom provider, adapter, or migration:
+
+```ts
+import {
+  runRegisteredSearchProviderForTest,
+  runRegisteredVectorStoreAdapterForTest,
+  runRegisteredMigrationForTest,
+} from "@unbrained/pm-cli/sdk/testing";
+
+// Invoke a registered provider's semantic query (or embed / embedBatch /
+// queryExpansion / rerank); the result type follows `operation`.
+const hits = await runRegisteredSearchProviderForTest(activation.registrations, {
+  provider: "semantic-local",
+  operation: "query",
+  context: { query: "calendar", mode: "semantic", tokens: ["calendar"], options: {}, settings, documents },
+});
+
+// Invoke a registered adapter's upsert / query / delete.
+await runRegisteredVectorStoreAdapterForTest(activation.registrations, {
+  adapter: "pinecone",
+  operation: "upsert",
+  context: { points: [{ id: "pm-1", vector }], settings },
+});
+
+// Invoke a registered migration's run with a host-shaped context.
+await runRegisteredMigrationForTest(activation.registrations, {
+  migration: "backfill-severity",
+  pmRoot,
+});
+```
+
 The bundled `pm-lifecycle-hooks` package is the first-party hooks exemplar. It
 declares only the `hooks` capability and registers a default-inert `afterCommand`
 hook, so package authors can copy a lifecycle pattern that does not write files,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.20",
+  "version": "2026.6.22",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -133,7 +133,7 @@
   },
   "devDependencies": {
     "@sentry/cli": "^3.5.1",
-    "@types/node": "^25.9.3",
+    "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "esbuild": "0.28.1",
     "tsx": "^4.22.4",

package/packages/pm-command-kit/README.md

@@ -70,3 +70,7 @@ Key conventions for authors:
 - `activation.commands` in `manifest.json` lists both package-owned commands and
   existing commands that receive injected flags so the host can lazily activate the
   extension before option validation.
+- Unit tests can validate this package's three command-facing registrations with
+  public SDK helpers: `assertRegisteredCommandContract(...)` for the owned command,
+  `assertRegisteredParserOverride(...)` for parser rewrites, and
+  `assertRegisteredFlags(...)` for the injected `pm list --kit-note` flag.