@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/docs/TESTING.md

@@ -9,7 +9,7 @@ This page describes safe local tests, linked tests, coverage, and release-readin
 - Linked tests added through `pm test` should use sandbox-safe commands.
 - Run linked tests before closing the item that owns the work.
 
-Tracked documentation work: [pm-1sb2](../.agents/pm/tasks/pm-1sb2.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ## Standard Local Checks
 
@@ -48,6 +48,23 @@ pm test-all --status in_progress --progress
 
 Do not link `pm test-all` itself as an item-level test command. It creates recursive orchestration.
 
+## Package Ecosystem Smoke
+
+After `pnpm build`, external package compatibility can be checked without
+touching the repository tracker:
+
+```bash
+pnpm smoke:external-packages -- --limit 10
+pnpm smoke:external-packages -- --package pm-changelog
+```
+
+The harness creates one temporary project per package, sets sandboxed `PM_PATH`
+and `PM_GLOBAL_PATH`, installs the package with `pm install npm:<name>
+--project`, runs `pm package doctor --project --detail deep --trace`, and probes
+runtime contracts with `pm contracts --runtime-only --availability-only`. Use
+`--discover-only` for the npm package list and `--keep-temp` only when debugging
+a failing package root.
+
 ## PM Context Modes
 
 Linked PM commands default to schema context: settings and extensions are seeded, but tracker item data stays isolated.
@@ -123,3 +140,21 @@ rg -n "forbidden-private-token-or-path" README.md docs
 ```
 
 Replace the placeholder pattern with the actual sensitive term being guarded in the current task.
+
+## Contract Snapshot Gate
+
+Tracked by [pm-d6kq](../.agents/pm/tasks/pm-d6kq.toon).
+
+`pm contracts --full --json` is a public machine-readable SDK and agent surface.
+Keep its committed golden snapshot current when command contracts, schemas,
+aliases, or extension-provided command contracts intentionally change:
+
+```bash
+pnpm build
+pnpm contracts:update
+pnpm contracts:check
+```
+
+CI runs `pnpm contracts:check` in the static gate. Snapshot diffs should be
+reviewed like an API change and paired with the package-owned changelog flow
+when the contract surface changes intentionally.

package/docs/examples/policy-restricted-extension/manifest.json

@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "manifest_version": 2,
+  "pm_min_version": "2026.5.0",
   "trusted": true,
   "provenance": {
     "source": "docs/examples/policy-restricted-extension",

package/docs/examples/starter-extension/index.js

@@ -94,8 +94,16 @@ export default defineExtension({
     });
 
     // renderers
-    api.registerRenderer("json", (context) => stableJson(context.result));
+    api.registerRenderer("json", (context) => {
+      if (context.command !== "starter ping") {
+        return null;
+      }
+      return stableJson(context.result);
+    });
     api.registerRenderer("toon", (context) => {
+      if (context.command !== "starter ping") {
+        return null;
+      }
       const result = asRecord(context.result);
       const hooks = asRecord(result.hook_counts);
       return [

package/docs/examples/starter-extension/manifest.json

@@ -4,6 +4,7 @@
   "description": "SDK-first starter extension demonstrating all pm extension capabilities.",
   "entry": "./index.js",
   "manifest_version": 2,
+  "pm_min_version": "2026.5.0",
   "trusted": true,
   "provenance": {
     "source": "docs/examples/starter-extension",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.5.31",
+  "version": "2026.6.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -33,6 +33,11 @@
       "import": "./dist/sdk/runtime.js",
       "default": "./dist/sdk/runtime.js"
     },
+    "./sdk/testing": {
+      "types": "./dist/sdk/testing.d.ts",
+      "import": "./dist/sdk/testing.js",
+      "default": "./dist/sdk/testing.js"
+    },
     "./cli": {
       "types": "./dist/cli/main.d.ts",
       "import": "./dist/cli/main.js",
@@ -69,7 +74,11 @@
     "test:coverage": "node scripts/run-tests.mjs coverage",
     "quality:static": "node scripts/release/static-quality-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
+    "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
+    "contracts:update": "node scripts/contracts-snapshot.mjs --update",
+    "contracts:check": "node scripts/contracts-snapshot.mjs --check",
     "dogfood:package-first": "node scripts/dogfood-package-first.mjs",
+    "smoke:external-packages": "node scripts/smoke-external-packages.mjs",
     "smoke:codex-plugin": "node scripts/smoke-codex-plugin-mcp.mjs",
     "smoke:claude-plugin": "node scripts/smoke-claude-plugin.mjs",
     "version:check": "node scripts/release-version.mjs check",
@@ -115,20 +124,20 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.55.0",
+    "@sentry/node": "^10.56.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
-    "@sentry/cli": "^3.4.3",
-    "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.7",
+    "@sentry/cli": "^3.5.0",
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "0.28.0",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.7"
+    "vitest": "^4.1.8"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/packages/pm-beads/extensions/beads/index.js

@@ -4,7 +4,7 @@ export const manifest = {
     version: "0.1.0",
     entry: "./index.js",
     priority: 0,
-    capabilities: ["commands", "schema"],
+    capabilities: ["commands", "schema", "importers"],
 };
 function asOptionalString(value) {
     return typeof value === "string" ? value : undefined;
@@ -28,8 +28,7 @@ async function runBeadsImportFromRuntime(options, global) {
     return runtime.runBeadsImport(options, global);
 }
 export function activate(api) {
-    api.registerCommand({
-        name: "beads import",
+    api.registerImporter("beads", async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global), {
         action: "beads-import",
         description: "Import Beads JSONL records into pm items.",
         flags: [
@@ -57,7 +56,6 @@ export function activate(api) {
                 description: "Preserve source IDs from Beads payload records when possible.",
             },
         ],
-        run: async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
     });
 }
 export default {

package/packages/pm-beads/extensions/beads/index.ts

@@ -1,4 +1,9 @@
-import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
+import type {
+  ExtensionApi,
+  GlobalOptions,
+  ImportExportContext,
+  ImportExportRegistrationOptions,
+} from "../../../../src/sdk/index.js";
 import type { BeadsImportOptions, BeadsImportResult } from "./runtime.js";
 import { loadPackageRuntimeModule } from "./runtime-loader.js";
 
@@ -7,7 +12,7 @@ export const manifest = {
   version: "0.1.0",
   entry: "./index.js",
   priority: 0,
-  capabilities: ["commands", "schema"],
+  capabilities: ["commands", "schema", "importers"],
 };
 
 type RuntimeModule = {
@@ -40,37 +45,42 @@ async function runBeadsImportFromRuntime(options: BeadsImportOptions, global: Gl
 }
 
 export function activate(api: ExtensionApi): void {
-  api.registerCommand({
-    name: "beads import",
-    action: "beads-import",
-    description: "Import Beads JSONL records into pm items.",
-    flags: [
-      {
-        long: "--file",
-        value_name: "path",
-        value_type: "string",
-        description: "Path to the Beads JSONL source file.",
-      },
-      {
-        long: "--author",
-        value_name: "author",
-        value_type: "string",
-        description: "Override import mutation author.",
-      },
-      {
-        long: "--message",
-        value_name: "text",
-        value_type: "string",
-        description: "Override import history message.",
-      },
-      {
-        long: "--preserve-source-ids",
-        value_type: "boolean",
-        description: "Preserve source IDs from Beads payload records when possible.",
-      },
-    ],
-    run: async (context) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
-  } satisfies CommandDefinition);
+  // First-party exemplar for the importers capability: registerImporter creates
+  // the `beads import` command path, and the options object keeps the command
+  // description + flags discoverable in help and runtime contracts.
+  api.registerImporter(
+    "beads",
+    async (context: ImportExportContext) => runBeadsImportFromRuntime(toBeadsImportOptions(context.options), context.global),
+    {
+      action: "beads-import",
+      description: "Import Beads JSONL records into pm items.",
+      flags: [
+        {
+          long: "--file",
+          value_name: "path",
+          value_type: "string",
+          description: "Path to the Beads JSONL source file.",
+        },
+        {
+          long: "--author",
+          value_name: "author",
+          value_type: "string",
+          description: "Override import mutation author.",
+        },
+        {
+          long: "--message",
+          value_name: "text",
+          value_type: "string",
+          description: "Override import history message.",
+        },
+        {
+          long: "--preserve-source-ids",
+          value_type: "boolean",
+          description: "Preserve source IDs from Beads payload records when possible.",
+        },
+      ],
+    } satisfies ImportExportRegistrationOptions,
+  );
 }
 
 export default {

package/packages/pm-beads/extensions/beads/manifest.json

@@ -3,5 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": [
+    "commands",
+    "schema",
+    "importers"
+  ],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": [
+      "beads import"
+    ]
+  }
 }

package/packages/pm-calendar/README.md

@@ -13,3 +13,9 @@ pm cal --json --view agenda --include reminders,events
 The package owns presentation commands for deadline, reminder, and scheduled event views. Core pm still owns item metadata such as `deadline`, `reminders`, and `events`, plus create/update parsing for those fields.
 
 Runtime sources are authored in TypeScript and use only the public `@unbrained/pm-cli/sdk` surface.
+
+## Recurrence Notes
+
+Recurring event `recur_count` values are counted from the event series `start`, not from the query window. For example, a daily event starting April 1 with `recur_count=3` has its counted occurrences on April 1, 2, and 3; querying April 10 does not restart the count.
+
+`recur_exdates` exclude occurrences by instant. Equivalent timestamp spellings such as `2026-04-02T09:00:00Z`, `2026-04-02T09:00:00.000Z`, and `2026-04-02T09:00:00.000+00:00` match the same generated occurrence.

package/packages/pm-calendar/extensions/calendar/index.js

@@ -40,7 +40,12 @@ const calendarFlags = [
   { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
-  { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
+  {
+    long: "--occurrence-limit",
+    value_name: "n",
+    value_type: "string",
+    description: "Cap generated occurrences per recurring event; stored recur_count starts at series start, not the query window.",
+  },
   { long: "--limit", value_name: "n", value_type: "string", description: "Limit returned event count." },
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ];

package/packages/pm-calendar/extensions/calendar/index.ts

@@ -47,7 +47,12 @@ const calendarFlags = [
   { long: "--include", value_name: "value", value_type: "string", description: "Include sources: deadlines|reminders|events|scheduled|all." },
   { long: "--recurrence-lookahead-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookahead days." },
   { long: "--recurrence-lookback-days", value_name: "n", value_type: "string", description: "Bound open-ended recurrence lookback days." },
-  { long: "--occurrence-limit", value_name: "n", value_type: "string", description: "Cap generated occurrences per recurring event." },
+  {
+    long: "--occurrence-limit",
+    value_name: "n",
+    value_type: "string",
+    description: "Cap generated occurrences per recurring event; stored recur_count starts at series start, not the query window.",
+  },
   { long: "--limit", value_name: "n", value_type: "string", description: "Limit returned event count." },
   { long: "--format", value_name: "value", value_type: "string", description: "Calendar output override: markdown|toon|json." },
 ] as const;

package/packages/pm-calendar/extensions/calendar/manifest.json

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema", "services"]
+  "capabilities": ["commands", "schema", "services"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["cal", "calendar"]
+  }
 }

package/packages/pm-governance-audit/extensions/governance-audit/manifest.json

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema"]
+  "capabilities": ["commands", "schema"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["comments-audit", "dedupe-audit", "normalize"]
+  }
 }

package/packages/pm-guide-shell/README.md

@@ -7,6 +7,8 @@ First-party package that restores optional guide and shell-completion UX in bare
 - `pm guide [topic]`
 - `pm completion [bash|zsh|fish]`
 - `pm completion-tags`
+- `pm completion-statuses`
+- `pm completion-types`
 
 ## Install
 
@@ -20,4 +22,6 @@ pm install guide-shell --project
 pm guide --list --json
 pm completion bash
 pm completion-tags
+pm completion-statuses
+pm completion-types
 ```

package/packages/pm-guide-shell/extensions/guide-shell/index.js

@@ -1,7 +1,9 @@
 import {
   renderGuideShellPackageOutput,
   runCompletionPackage,
+  runCompletionStatusesPackage,
   runCompletionTagsPackage,
+  runCompletionTypesPackage,
   runGuidePackage,
 } from "./runtime.js";
 
@@ -60,10 +62,30 @@ function completionTagsCommand() {
   };
 }
 
+function completionStatusesCommand() {
+  return {
+    name: "completion-statuses",
+    action: "completion-statuses",
+    description: "Print runtime status IDs for completion filters.",
+    run: async (context) => runCompletionStatusesPackage(context.global),
+  };
+}
+
+function completionTypesCommand() {
+  return {
+    name: "completion-types",
+    action: "completion-types",
+    description: "Print runtime item type IDs for completion filters.",
+    run: async (context) => runCompletionTypesPackage(context.global),
+  };
+}
+
 export function activate(api) {
   api.registerCommand(guideCommand());
   api.registerCommand(completionCommand());
   api.registerCommand(completionTagsCommand());
+  api.registerCommand(completionStatusesCommand());
+  api.registerCommand(completionTypesCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context);
     return rendered ?? null;

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -6,7 +6,9 @@ import type {
 import {
   renderGuideShellPackageOutput,
   runCompletionPackage,
+  runCompletionStatusesPackage,
   runCompletionTagsPackage,
+  runCompletionTypesPackage,
   runGuidePackage,
 } from "./runtime.js";
 
@@ -65,10 +67,30 @@ function completionTagsCommand(): CommandDefinition {
   };
 }
 
+function completionStatusesCommand(): CommandDefinition {
+  return {
+    name: "completion-statuses",
+    action: "completion-statuses",
+    description: "Print runtime status IDs for completion filters.",
+    run: async (context) => runCompletionStatusesPackage(context.global),
+  };
+}
+
+function completionTypesCommand(): CommandDefinition {
+  return {
+    name: "completion-types",
+    action: "completion-types",
+    description: "Print runtime item type IDs for completion filters.",
+    run: async (context) => runCompletionTypesPackage(context.global),
+  };
+}
+
 export function activate(api: ExtensionApi): void {
   api.registerCommand(guideCommand());
   api.registerCommand(completionCommand());
   api.registerCommand(completionTagsCommand());
+  api.registerCommand(completionStatusesCommand());
+  api.registerCommand(completionTypesCommand());
   api.registerService("output_format", (context) => {
     const rendered = renderGuideShellPackageOutput(context as ServiceOverrideContext);
     return rendered ?? null;

package/packages/pm-guide-shell/extensions/guide-shell/manifest.json

@@ -3,5 +3,10 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
-  "capabilities": ["commands", "schema", "services"]
+  "capabilities": ["commands", "schema", "services"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.5.0",
+  "activation": {
+    "commands": ["completion", "completion-statuses", "completion-tags", "completion-types", "guide"]
+  }
 }

package/packages/pm-guide-shell/extensions/guide-shell/runtime.js

@@ -79,12 +79,38 @@ function normalizeCompletionOptions(bundle, args, options) {
   };
 }
 
+function collectTypeNames(typeRegistry) {
+  const candidates = Array.isArray(typeRegistry.types)
+    ? typeRegistry.types
+    : Array.isArray(typeRegistry.definitions)
+      ? typeRegistry.definitions
+          .filter((definition) => Boolean(definition))
+          .map((definition) => definition.name)
+      : [];
+  return [...new Set(candidates.filter((value) => typeof value === "string" && value.trim().length > 0))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function collectTypeToFolder(typeRegistry) {
+  if (typeof typeRegistry.type_to_folder === "object" && typeRegistry.type_to_folder !== null) {
+    return typeRegistry.type_to_folder;
+  }
+  return Object.fromEntries(
+    (typeRegistry.definitions ?? [])
+      .filter((definition) => Boolean(definition?.name && definition?.folder))
+      .map((definition) => [definition.name, definition.folder]),
+  );
+}
+
 async function buildCompletionRuntimeConfig(bundle, global) {
   const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
   if (!(await bundle.sdk.pathExists(bundle.sdk.getSettingsPath(pmRoot)))) {
     return {};
   }
   const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const itemTypes = collectTypeNames(typeRegistry);
   const schema = settings.schema;
   const statuses = bundle.sdk.resolveRuntimeStatusRegistry(schema).definitions
     .map((definition) => definition.id)
@@ -108,6 +134,7 @@ async function buildCompletionRuntimeConfig(bundle, global) {
     }
   }
   return {
+    item_types: itemTypes.length > 0 ? itemTypes : undefined,
     statuses: statuses.length > 0 ? statuses : undefined,
     command_flags: Object.keys(commandFlags).length > 0 ? commandFlags : undefined,
   };
@@ -170,9 +197,7 @@ export async function runCompletionTagsPackage(global) {
   const settings = await bundle.sdk.readSettings(pmRoot);
   const registrations = bundle.sdk.getActiveExtensionRegistrations();
   const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
-  const typeToFolder = Object.fromEntries(
-    typeRegistry.definitions.map((definition) => [definition.name, definition.folder]),
-  );
+  const typeToFolder = collectTypeToFolder(typeRegistry);
   const schema = settings.schema;
   const itemFormat = settings.item_format === "json_markdown" ? "json_markdown" : "toon";
   const items = await bundle.sdk.listAllFrontMatter(pmRoot, itemFormat, typeToFolder, undefined, schema);
@@ -183,6 +208,34 @@ export async function runCompletionTagsPackage(global) {
   };
 }
 
+export async function runCompletionStatusesPackage(global) {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const schema = settings.schema;
+  const statuses = bundle.sdk.resolveRuntimeStatusRegistry(schema).definitions
+    .map((definition) => definition.id)
+    .filter((status) => typeof status === "string" && status.trim().length > 0)
+    .sort((left, right) => left.localeCompare(right));
+  return {
+    statuses,
+    count: statuses.length,
+  };
+}
+
+export async function runCompletionTypesPackage(global) {
+  const bundle = await ensureRuntimeBundle();
+  const pmRoot = bundle.sdk.resolvePmRoot(process.cwd(), global.path);
+  const settings = await bundle.sdk.readSettings(pmRoot);
+  const registrations = bundle.sdk.getActiveExtensionRegistrations();
+  const typeRegistry = bundle.sdk.resolveItemTypeRegistry(settings, registrations);
+  const types = collectTypeNames(typeRegistry);
+  return {
+    types,
+    count: types.length,
+  };
+}
+
 export function renderGuideShellPackageOutput(context) {
   if (!runtimeBundle) {
     return null;
@@ -219,5 +272,23 @@ export function renderGuideShellPackageOutput(context) {
       : [];
     return `${tags.join(" ")}\n`;
   }
+  if (context.command === "completion-statuses") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const statuses = typeof result === "object" && result !== null && Array.isArray(result.statuses)
+      ? result.statuses.filter((entry) => typeof entry === "string")
+      : [];
+    return `${statuses.join(" ")}\n`;
+  }
+  if (context.command === "completion-types") {
+    if (readPayloadFormat(context.payload) === "json") {
+      return `${JSON.stringify(result, null, 2)}\n`;
+    }
+    const types = typeof result === "object" && result !== null && Array.isArray(result.types)
+      ? result.types.filter((entry) => typeof entry === "string")
+      : [];
+    return `${types.join(" ")}\n`;
+  }
   return null;
 }