@unbrained/pm-cli 2026.6.9 → 2026.6.10

package/docs/EXTENSIONS.md

@@ -52,8 +52,7 @@ pm github validate --repo owner/repo
 
 For `pm-github`, run `pm github validate --repo owner/repo` before mutating commands; write paths require `GITHUB_TOKEN`/`GH_TOKEN` or `gh auth login`.
 
-For ecosystem maintenance, use the reusable external package smoke harness after
-building `dist/`:
+For ecosystem maintenance, use the reusable external package smoke harness after building `dist/`:
 
 ```bash
 pnpm build
@@ -61,11 +60,7 @@ pnpm smoke:external-packages -- --limit 10
 pnpm smoke:external-packages -- --package pm-changelog
 ```
 
-The harness discovers npm packages with the `keywords:pm-package` query unless
-explicit packages are provided. Each package is installed in a temporary project
-with isolated `PM_PATH` and `PM_GLOBAL_PATH`, then checked with `pm package
-doctor --project --detail deep --trace` and runtime availability contracts. The
-JSON output is compact enough for agents to attach as tracker evidence.
+The harness discovers npm packages with the `keywords:pm-package` query unless explicit packages are provided, installs each package in a temporary project with isolated `PM_PATH`/`PM_GLOBAL_PATH`, then checks `pm package doctor --project --detail deep --trace` and runtime availability contracts.
 
 Prefer package-specific docs before invoking commands that require service credentials, such as GitHub, Jira, Linear, or Slack sync packages.
 
@@ -82,29 +77,13 @@ Package roots declare resources in `package.json` under `pm`:
     "extensions": ["."],
     "docs": ["README.md"],
     "examples": ["examples/basic.md"],
-    "catalog": {
-      "display_name": "My pm Package",
-      "category": "workflow",
-      "summary": "Adds a custom workflow to pm.",
-      "tags": ["workflow"],
-      "links": {
-        "docs": "https://example.com/docs",
-        "repository": "https://github.com/org/my-pm-package",
-        "report": "https://github.com/org/my-pm-package/issues"
-      }
-    }
+    "assets": ["assets"],
+    "prompts": ["prompts"],
+    "catalog": { "display_name": "My pm Package", "category": "workflow" }
   }
 }
 ```
 
-Current resource kinds are:
-
-- `extensions`
-- `docs`
-- `examples`
-- `assets`
-- `prompts`
-
 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`.
@@ -142,6 +121,16 @@ A minimal standalone extension has a `manifest.json` and an import-free entrypoi
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",
   "pm_max_version": "2027.0.0",
+  "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"]
 }
 ```
@@ -194,16 +183,19 @@ Runnable manifest examples are the source of truth:
 - [starter extension manifest](examples/starter-extension/manifest.json)
 - [policy-restricted manifest](examples/policy-restricted-extension/manifest.json)
 
+Schema:
+
+- Use [extension-manifest.schema.json](schemas/extension-manifest.schema.json) as the
+  `$schema` value for inline editor validation. The loader ignores `$schema` and
+  tolerates future manifest fields, but the schema documents the fields pm reads.
+
 Rules:
 
 - `entry` must resolve inside the extension directory.
 - `manifest_version` is an optional integer identifying the manifest schema generation. Runtime contracts currently support manifest versions `1` and `2`, and first-party runnable examples use `2`. First-party packages declare it; the manifest governance test requires it on every first-party package.
 - `pm_min_version` is an inclusive minimum pm CLI version. If the running CLI is older, discovery emits `extension_pm_min_version_unmet:<layer>:<name>:required=<version>:current=<version>` and skips the extension before import.
-- `pm_max_version` is an optional inclusive maximum pm CLI version (the upper compatibility bound). If the running CLI is newer than this value, discovery emits `extension_pm_max_version_exceeded:<layer>:<name>:allowed=<version>:current=<version>` and skips the extension before import. Use it to stop a CLI major release from loading a stale package that would crash at activation.
-- Both bounds share the same blocking semantics and warning-code shapes:
-  - `*_invalid` (`required=`/`allowed=` only): the declared version is unparseable; the extension is **blocked**.
-  - `*_unchecked` (`...:current=unknown` or an uncomparable current version): the bound could not be compared against the running CLI; the extension is **allowed** but a warning is recorded.
-  - `extension_pm_min_version_unmet` / `extension_pm_max_version_exceeded`: the running CLI is outside the declared bound; the extension is **blocked**.
+- `pm_max_version` is an optional inclusive maximum pm CLI version (the upper compatibility bound). If the running CLI is newer than this value, discovery emits `extension_pm_max_version_exceeded:<layer>:<name>:allowed=<version>:current=<version>` and skips the extension before import. Use it to stop a CLI major release from loading a stale package that would crash at activation. Operators can temporarily set `extensions.policy.pm_max_version_exceeded_mode` to `"warn"` (or `{ "project": "warn" }`) during controlled upgrade windows; the default remains `"block"`.
+- 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.
@@ -224,9 +216,16 @@ Supported capabilities:
 
 First-party package exemplars:
 
-- `pm-beads` and `pm-todos`: importer/exporter registration and generated command contracts.
+- `pm-beads`: beads JSON/JSONL importer/exporter package with generated command contracts.
+- `pm-calendar`: calendar view package for schedule/context surfaces.
+- `pm-command-kit`: command capability exemplar for `registerCommand`, `registerFlags`, and `registerParser`.
+- `pm-governance-audit`: governance hook exemplar for compact read/write sidecar logs.
+- `pm-guide-shell`: guide-topic package for bundled workflow docs.
 - `pm-lifecycle-hooks`: default-inert lifecycle hook registration.
+- `pm-linked-test-adapters`: linked-test run-management adapters and reporters.
 - `pm-search-advanced`: deterministic local search provider registration.
+- `pm-templates`: reusable create-template package.
+- `pm-todos`: todo import/export package with generated command contracts.
 
 ## Governance Policy
 
@@ -244,27 +243,30 @@ Sandbox profiles:
 - `restricted`: safe default for normal package workflows
 - `strict`: most restrictive policy profile
 
-Surface tokens include:
-
-- `commands.handler`
-- `commands.override`
-- `parser.override`
-- `preflight.override`
-- `services.override`
-- `renderers.override`
-- `hooks.beforecommand`
-- `hooks.aftercommand`
-- `hooks.onwrite`
-- `hooks.onread`
-- `hooks.onindex`
-- `schema.flags`
-- `schema.itemfields`
-- `schema.itemtypes`
-- `schema.migrations`
-- `importers`
-- `search.provider`
+`sandbox_profile` and `permissions` are declaration-based load gates, not runtime
+isolation. They let policy decide whether to load an extension; they do not stop
+loaded JavaScript from using Node APIs at runtime. `pm package doctor --project`
+reports the same advisory trust-model caveat in its policy summary.
+
+`extensions.policy.pm_max_version_exceeded_mode` controls how `pm_max_version`
+violations are handled. Use `"block"` (the default) for both global and project
+layers, `"warn"` to allow exceeded extensions while emitting
+`extension_pm_max_version_exceeded_warn`, or a per-layer object such as:
+
+```json
+{
+  "extensions": {
+    "policy": {
+      "pm_max_version_exceeded_mode": {
+        "global": "block",
+        "project": "warn"
+      }
+    }
+  }
+}
+```
 
-Use `pm package doctor --project --detail deep --trace` to inspect active policy state and warning codes.
+Surface tokens include command handlers/overrides, parser/preflight/services/renderers overrides, lifecycle hooks, schema registrations, importers, and search providers. Use `pm package doctor --project --detail deep --trace` for the exact active token names and policy warning codes.
 
 ## Registration Collisions
 
@@ -303,7 +305,7 @@ Common APIs:
   item entries for mutations, including `previous_status`, `status`,
   `changed_fields`, and partial `previous`/`current` front matter snapshots.
   `onWrite` always includes `path`, `scope`, and `op`; item mutations also add optional `item_id`, `item_type`, `before`, `after`, and `changed_fields`.
-- An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and never blocks other extensions.
+- An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
 
 The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only
 `hooks` and registers a default-inert `afterCommand` hook so authors can copy a

package/docs/SDK.md

@@ -263,6 +263,10 @@ Manifest typing also accepts optional `engines` metadata:
 
 Use `pm_min_version` for the loader gate. Keep `engines` as package-manager and tooling metadata.
 
+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).
+
 ## Self-Identity and Lifecycle
 
 `activate(api)` receives a read-only `api.extension` describing the extension it
@@ -291,8 +295,10 @@ native-action requests — so an extension can close connections, clear timers,
 release buffers opened during `activate`. `deactivate` runs only for extensions
 that activated successfully (a failed `activate` never fully initialized), and
 teardowns run concurrently. Teardown is best-effort: a throwing `deactivate` is
-recorded as a warning, never propagated, so one extension cannot block another's
-cleanup.
+recorded as a warning, never propagated, and each hook is bounded by a host
+timeout so one extension cannot block another's cleanup or a host reload. Hosts
+that call `deactivateExtensions` directly may pass `deactivate_timeout_ms: 0` or
+`Infinity` only when they intentionally want to wait indefinitely.
 
 ```ts
 export default defineExtension({

package/docs/TESTING.md

@@ -31,6 +31,38 @@ node scripts/run-tests.mjs test -- tests/integration/cli.integration.spec.ts
 
 Use focused runs while iterating, then run coverage before closure when risk or scope warrants it.
 
+## Coverage Governance
+
+Coverage gating now targets literal source coverage for `src/`:
+
+- `vitest.config.ts` includes `src/*.ts` and `src/**/*.ts`.
+- Thresholds are explicit ratchet baselines for the measured all-source corpus and should only move upward until they reach 100%.
+- Avoid reintroducing a curated `include`/`exclude` allowlist for production `src` modules.
+- Prefer extracting deterministic pure helpers (and unit-testing them) when an orchestration-heavy file is difficult to cover directly.
+
+## Search Quality Evaluation
+
+`search-advanced` exposes an advisory golden-query harness for relevance drift checks.
+
+Fixture source:
+
+- `tests/search-eval/golden-queries.json`
+
+Local run:
+
+```bash
+pm install search-advanced --project
+pm reindex --mode keyword --eval --eval-fixtures tests/search-eval/golden-queries.json --json
+```
+
+Fixture authoring notes:
+
+- Each fixture must include `query`, `expected_top_ids`, and optionally `mode` (`keyword|semantic|hybrid`) and `min_ndcg_at_5` (`0..1`).
+- Keep expected IDs deterministic and scoped to stable seed data so CI does not flap.
+- Add new fixtures for regressions before tuning search defaults.
+
+CI currently runs this gate in advisory mode (`continue-on-error: true`), so failures do not block merges by default; treat failing nDCG as a quality signal to investigate, not as a silent ignore.
+
 ## Linked Tests
 
 Add tests to the item that owns the work:
@@ -77,6 +109,20 @@ pm test <item-id> --run --pm-context tracker
 pm test <item-id> --run --pm-context auto --check-context --auto-pm-context
 ```
 
+For complex linked-test commands, prefer JSON input so shell syntax survives unchanged:
+
+```bash
+pm test <item-id> --add-json '{"command":"node scripts/run-tests.mjs test -- tests/unit/output.spec.ts","timeout_seconds":240}'
+```
+
+To rerun a focused subset without editing linked-test metadata:
+
+```bash
+pm test <item-id> --run --match output
+pm test <item-id> --run --only-index 2
+pm test <item-id> --run --only-last
+```
+
 Strict governance flags:
 
 ```bash
@@ -120,6 +166,20 @@ pm test-runs resume <run-id>
 
 Background run fingerprints prevent duplicate parallel runs for the same linked-test set.
 
+The bundled `pm-linked-test-adapters` package is the first-party package
+exemplar for background run management. Install it in an isolated project when
+validating package-provided test-run surfaces:
+
+```bash
+pm install linked-test-adapters --project
+pm package doctor --project --detail deep --trace
+pm test-runs list --json
+```
+
+The package activates the `test-runs` command family and keeps subprocess
+handling behind an explicit package permission declaration, so it is a useful
+smoke target for package, permission, and command-contract changes.
+
 ## Release-Readiness Checks
 
 For substantial changes:

package/docs/schemas/extension-manifest.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/unbraind/pm-cli/main/docs/schemas/extension-manifest.schema.json",
+  "title": "pm extension manifest",
+  "description": "Schema for a pm extension's manifest.json. The loader tolerates unknown fields (including $schema), so additionalProperties stays true; only the fields listed here are read. Note: sandbox_profile and permissions are advisory, declaration-based load gates — pm does not isolate extension code at runtime (ADR pm-6ef3).",
+  "type": "object",
+  "required": ["name", "version", "entry"],
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for inline IDE validation. Ignored by the loader."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique extension name. A project-layer extension with the same name overrides a global-layer one."
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Extension version (semver recommended)."
+    },
+    "entry": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the entry module, relative to the extension directory. Must resolve inside the extension directory."
+    },
+    "priority": {
+      "type": "integer",
+      "description": "Load-order priority within a layer (lower loads first). Defaults to 100."
+    },
+    "manifest_version": {
+      "type": "integer",
+      "enum": [1, 2],
+      "description": "Optional manifest format version."
+    },
+    "pm_min_version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Minimum compatible pm CLI version. A leading \">=\" prefix is accepted. Unmet minimums block loading.",
+      "examples": ["2026.5.0", ">=2026.5.0"]
+    },
+    "pm_max_version": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^<>=~^]",
+      "description": "Maximum compatible pm CLI version as an exact version (range prefixes like >=, <, ~, ^ are rejected). Exceeding it blocks loading by default; extensions.policy.pm_max_version_exceeded_mode can relax this to warn-only.",
+      "examples": ["2026.12.31"]
+    },
+    "engines": {
+      "type": "object",
+      "description": "Engine compatibility declarations (e.g. pm, node). Every value must be a non-empty string.",
+      "additionalProperties": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "trusted": {
+      "type": "boolean",
+      "description": "Declares the extension as trusted for extensions.policy.trust_mode evaluation."
+    },
+    "provenance": {
+      "type": "object",
+      "description": "Optional provenance metadata used by require_provenance policy checks.",
+      "properties": {
+        "source": { "type": "string", "minLength": 1 },
+        "signature": { "type": "string", "minLength": 1 },
+        "attestation": { "type": "string", "minLength": 1 },
+        "verified": { "type": "boolean" }
+      }
+    },
+    "sandbox_profile": {
+      "type": "string",
+      "enum": ["none", "restricted", "strict"],
+      "description": "Advisory sandbox profile evaluated against declared permissions when extensions.policy.mode is active. Declaration-based load gate only — not runtime isolation (ADR pm-6ef3)."
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Advisory runtime permission declarations checked against the sandbox profile. Not enforced at runtime (ADR pm-6ef3).",
+      "properties": {
+        "fs_read": { "type": "boolean" },
+        "fs_write": { "type": "boolean" },
+        "network": { "type": "boolean" },
+        "env_read": { "type": "boolean" },
+        "env_write": { "type": "boolean" },
+        "process_spawn": { "type": "boolean" }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "Capabilities the extension's registrations may use. Known: commands, renderers, hooks, schema, importers, search, parser, preflight, services (legacy aliases migration/validation map to schema). Unknown values only warn.",
+      "items": {
+        "type": "string",
+        "examples": [
+          "commands",
+          "renderers",
+          "hooks",
+          "schema",
+          "importers",
+          "search",
+          "parser",
+          "preflight",
+          "services"
+        ]
+      }
+    },
+    "activation": {
+      "type": "object",
+      "description": "Lazy-activation metadata.",
+      "properties": {
+        "commands": {
+          "type": "array",
+          "description": "Command names that trigger activation.",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.6.9",
+  "version": "2026.6.10",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -125,7 +125,7 @@
     }
   },
   "dependencies": {
-    "@sentry/node": "^10.56.0",
+    "@sentry/node": "^10.57.0",
     "@toon-format/toon": "^2.3.0",
     "commander": "^14.0.3",
     "fast-glob": "^3.3.3",

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

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "restricted",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": true,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": [
     "commands",
     "schema",

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

@@ -3,6 +3,16 @@
   "version": "0.1.0",
   "entry": "./index.js",
   "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": true,
+    "fs_write": false,
+    "network": false,
+    "env_read": true,
+    "env_write": false,
+    "process_spawn": false
+  },
   "capabilities": ["commands", "schema", "services"],
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",

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

@@ -0,0 +1,72 @@
+# @unbrained/pm-command-kit
+
+First-party **exemplar package** for the pm extension `commands` capability. Copy this
+package wholesale when you want to ship your own pm command: it demonstrates the three
+command-facing SDK registration APIs in their smallest complete form.
+
+## What it demonstrates
+
+| API | What the exemplar does |
+| --- | --- |
+| `api.registerCommand(definition)` | Registers `pm command-kit echo` with a FULL `CommandDefinition`: `name`, `action`, `description`, `intent`, `arguments` (required variadic positional), `flags`, `examples`, `failure_hints`, and a pure `run` handler. |
+| `api.registerParser(command, override)` | Preprocesses parsed options before the handler runs: rewrites the deprecated `--shout` alias to `--upper`, coerces `--repeat` to a positive integer, and trims/dedupes `--decorations` values. The override returns a delta (`{ options }`) that is merged over the parsed input. |
+| `api.registerFlags(targetCommand, flags)` | Injects an inert, namespaced `--kit-note <text>` flag into the EXISTING core `pm list` command — the pattern for augmenting commands you do not own. |
+
+## Install
+
+```bash
+pm install command-kit --project
+```
+
+## Usage
+
+```bash
+pm command-kit echo "hello world"
+pm command-kit echo hello --upper --repeat 2
+pm command-kit echo hello --decorations star,spark --decorations wave
+pm command-kit echo hello --shout            # parser rewrites --shout to --upper
+pm list --kit-note "triage pass"             # injected flag; core list ignores it
+```
+
+The command returns a structured result (rendered as TOON or JSON by the host):
+
+```json
+{
+  "action": "command-kit-echo",
+  "message": "HELLO",
+  "lines": ["HELLO", "HELLO"],
+  "repeat": 2,
+  "upper": true,
+  "decorations": []
+}
+```
+
+## Package anatomy
+
+```
+packages/pm-command-kit/
+├── package.json                       # pm resources: aliases, extensions, catalog, docs
+├── README.md
+└── extensions/command-kit/
+    ├── manifest.json                  # capabilities, trusted, sandbox_profile, permissions
+    ├── index.ts                       # TypeScript source (type-only SDK imports)
+    └── index.js                       # hand-maintained runtime module (import-free)
+```
+
+Key conventions for authors:
+
+- `index.js` is what actually runs. It is **import-free** so the extension loads in
+  extension-only installs without SDK module resolution. `index.ts` mirrors it with
+  `import type { ... } from` the SDK for editor/typecheck support; type-only imports are
+  erased and keep the shipped `.js` dependency-free.
+- The module's `manifest.capabilities` literal must match `manifest.json` exactly
+  (`commands` for `registerCommand`, `schema` for flag definitions/`registerFlags`,
+  `parser` for `registerParser`).
+- This extension is pure compute (no fs/network/env/process access), so the manifest
+  declares `"trusted": true`, `"sandbox_profile": "strict"`, and all six permission keys
+  (`fs_read`, `fs_write`, `network`, `env_read`, `env_write`, `process_spawn`) as `false`.
+  Declare only what your extension actually does — the extension policy engine evaluates
+  these fields when sandbox/trust enforcement is enabled.
+- `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.