@unbrained/pm-cli 2026.7.2 → 2026.7.4

package/docs/EXTENSIONS.md

@@ -86,7 +86,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": ["."]`) authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a typed `index.ts`, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts, with the manifest `entry` pointing at `./index.ts` itself. pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). 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. `--capability schema` keeps the starter command and registers a custom item type, item field, and migration via `api.registerItemTypes`, `api.registerItemFields`, and `api.registerMigration`, with SDK tests using `assertRegisteredItemType`, `assertRegisteredItemField`, `assertRegisteredMigration`, and `runRegisteredMigrationForTest`; it deliberately omits `activation.commands` because a custom item type is a global contribution that built-in commands (`pm create <type>`, `pm list`, `pm validate`) must see, so pm activates it conservatively for every command. `--capability profile` keeps the starter command and registers a complete project-profile archetype — item types, custom statuses, fields, a per-type workflow, config knobs, a create template, and package recommendations — via `api.registerProfile`, with an SDK test using the harness-bound `assertProfile` (the public `assertRegisteredProfile`); like the schema starter it omits `activation.commands` because the contributed profile is resolved by the built-in `pm profile list/show/apply` commands (granted by the same `schema` capability, since a profile is a schema+config bundle), so pm activates it conservatively for every command and `pm profile apply <name>` tailors a fresh tracker in one shot. The remaining four capabilities complete the matrix to one starter per SDK registration surface. `--capability renderers` keeps the starter command and adds a `toon` output renderer override via `api.registerRenderer` (scoped to its own command — it returns `null` to pass other output through to pm's default renderer) plus SDK tests with `assertRegisteredRendererOverride` and `runRegisteredRendererOverrideForTest`. `--capability parser` adds a parser override via `api.registerParser` that rewrites the command's parsed options before its handler runs (a deprecated `--shout`→`--upper` alias rewrite); the starter command declares the matching `--shout`/`--upper` flags and surfaces the normalized value so the override is runnable end to end through `pm <command> --shout`, and the manifest also declares `schema` because flag metadata is schema-governed, with SDK tests using `assertRegisteredParserOverride` and `runRegisteredParserOverrideForTest`. `--capability preflight` adds a preflight override via `api.registerPreflight` over pm's pre-run migration/format gate decision (a safe no-op echo by default) plus SDK tests with `assertRegisteredPreflightOverride` and `runRegisteredPreflightOverrideForTest`. `--capability services` overrides the built-in `output_format` service via `api.registerService` (scoped to its own command, passing other commands' output through) plus SDK tests with `assertRegisteredServiceOverride` and `runRegisteredServiceOverrideForTest`. 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`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
+`pm package init` emits a root extension (`"extensions": ["."]`) authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a typed `index.ts`, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts, with the manifest `entry` pointing at `./index.ts` itself. pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). `--capability` selects one of ten starters — one per SDK registration surface (`commands`, `hooks`, `search`, `importers`, `schema`, `profile`, `renderers`, `parser`, `preflight`, `services`) — each keeping a runnable starter command and adding the surface's registration plus a colocated `node:test` suite built on the matching SDK `assertRegistered*`/`runRegistered*ForTest` helpers. The full per-capability matrix (what each starter registers, which starters also declare `schema` because flag metadata is schema-governed, and why `schema`/`profile` omit `activation.commands` so their global contributions activate conservatively for every command) lives in [SDK.md — Minimal Command Extension](./SDK.md#minimal-command-extension). 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`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
 
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
@@ -217,17 +217,17 @@ Supported capabilities:
 
 First-party package exemplars:
 
-- `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-kanban`: archetype exemplar shipping a complete Kanban continuous-flow profile (Card type, flow fields, and a `ProjectProfileDefinition`) on public SDK primitives.
-- `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.
+- [`pm-beads`](../packages/pm-beads/README.md): beads JSON/JSONL importer/exporter package with generated command contracts.
+- [`pm-calendar`](../packages/pm-calendar/README.md): calendar view package for schedule/context surfaces.
+- [`pm-command-kit`](../packages/pm-command-kit/README.md): command capability exemplar for `registerCommand`, `registerFlags`, and `registerParser`.
+- [`pm-governance-audit`](../packages/pm-governance-audit/README.md): governance hook exemplar for compact read/write sidecar logs.
+- [`pm-guide-shell`](../packages/pm-guide-shell/README.md): guide-topic package for bundled workflow docs.
+- [`pm-kanban`](../packages/pm-kanban/README.md): archetype exemplar shipping a complete Kanban continuous-flow profile (Card type, flow fields, and a `ProjectProfileDefinition`) on public SDK primitives.
+- [`pm-lifecycle-hooks`](../packages/pm-lifecycle-hooks/README.md): default-inert lifecycle hook registration.
+- [`pm-linked-test-adapters`](../packages/pm-linked-test-adapters/README.md): linked-test run-management adapters and reporters.
+- [`pm-search-advanced`](../packages/pm-search-advanced/README.md): deterministic local search provider registration.
+- [`pm-templates`](../packages/pm-templates/README.md): reusable create-template package.
+- [`pm-todos`](../packages/pm-todos/README.md): todo import/export package with generated command contracts.
 
 ## Governance Policy
 

package/docs/ONBOARDING.md

@@ -14,7 +14,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon), [pm-oh5
 
 ## Prerequisites
 
-- Node.js 20 or newer
+- Node.js 22.18 or newer
 - pnpm 10 or newer
 - Git + GitHub CLI (`gh`) authenticated for this repository
 
@@ -74,6 +74,8 @@ pm validate --check-resolution --check-history-drift
 
 ## Real Tracker Workflow (Canonical Loop)
 
+The canonical loop is maintained in [AGENT_GUIDE.md](AGENT_GUIDE.md) — this is the condensed contributor version.
+
 1) Orient and dedupe
 
 ```bash
@@ -141,7 +143,7 @@ pnpm release:pipeline
 ```bash
 pm health --check-only
 pm validate --check-resolution --check-history-drift
-pm normalize --dry-run --json
+pm normalize --dry-run --json   # requires the governance-audit package
 pm package doctor --project --detail summary
 pm contracts --command <command> --flags-only --json
 ```

package/docs/README.md

@@ -61,6 +61,8 @@ pm guide release --json
 
 Community files:
 
+- [Agent operating rules](../AGENTS.md)
+- [Product requirements](../PRD.md)
 - [Contributing](../CONTRIBUTING.md)
 - [Security](../SECURITY.md)
 - [Code of Conduct](../CODE_OF_CONDUCT.md)

package/docs/examples/starter-extension/README.md

@@ -36,28 +36,29 @@ cd .agents/pm/extensions/starter-extension
 npm install
 cd -
 
-# 3) Install/activate in project scope
-pm extension --install --project .agents/pm/extensions/starter-extension
+# 3) Install/activate in project scope (package-first vocabulary;
+#    `pm extension --install` remains as a compatibility form)
+pm install .agents/pm/extensions/starter-extension --project
 
 # 4) Run a starter command
 pm starter ping --name "agent"
 
 # 5) Reload extension modules after edits
-pm extension --reload --project
+pm package --reload --project
 
 # 6) Optional watch-mode semantics
-pm extension --reload --project --watch
+pm package --reload --project --watch
 
 # 7) Verify runtime health
-pm extension --doctor --project --detail summary
+pm package doctor --project --detail summary
 ```
 
 Expected outcomes:
 
 - `pm starter ping` returns deterministic output (plain text when starter service overrides output formatting).
-- `extension --doctor` shows `details.summary.status` as `ok` or `warn`.
+- `pm package doctor` shows `details.summary.status` as `ok` or `warn`.
 - If `warn`, inspect `details.summary.warning_codes` and `details.triage.remediation`.
-- `extension --reload` returns deterministic load/activation diagnostics for cache-busted imports.
+- `pm package --reload` returns deterministic load/activation diagnostics for cache-busted imports.
 
 ## Policy-Restricted Variant
 
@@ -65,15 +66,15 @@ To test governance controls with this extension:
 
 1. Set `settings.extensions.policy.mode` to `warn` or `enforce`.
 2. Block one surface (for example `commands.override`).
-3. Re-run `pm extension --doctor --detail summary`.
+3. Re-run `pm package doctor --detail summary`.
 
 You should see `extension_policy_*` warnings and policy counters in `details.triage`.
 
 ## CI-Friendly Verification Commands
 
 ```bash
-pm contracts --command extension --flags-only --json
-pm extension --doctor --project --detail summary --strict-exit
+pm contracts --command package --flags-only --json
+pm package doctor --project --detail summary --strict-exit
 node scripts/run-tests.mjs test -- tests/unit/extension-loader.spec.ts tests/unit/extension-command.spec.ts
 ```
 

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "1.4.0"
+    "version": "1.4.1"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
-      "description": "Native pm CLI integration for Claude Code — 25 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "1.4.0",
+      "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
+      "version": "1.4.1",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.2",
+  "version": "2026.7.4",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",
@@ -140,15 +140,16 @@
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-v8": "^4.1.9",
     "esbuild": "0.28.1",
     "eslint": "^10.6.0",
-    "eslint-plugin-unicorn": "^69.0.0",
+    "eslint-plugin-unicorn": "^70.0.0",
     "greptile": "^3.1.1",
     "jscpd": "^5.0.11",
-    "tsx": "^4.22.4",
+    "tsx": "^4.23.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.62.1",
     "vitest": "^4.1.9"

package/packages/pm-beads/extensions/beads/runtime-loader.ts

@@ -5,16 +5,12 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 /**
  * This file is auto-generated by scripts/gen-package-runtime-loaders.mjs.
  * Do not edit directly.
- * This file is shipped with the package extension and intentionally avoids
- * static SDK imports so project-local installed extensions can load it.
  */
-
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const EXTENSION_NAME = "beads";
 const PACKAGE_NAME = "pm-beads";
 const DIAGNOSTIC_NAME = "beads";
-
 export type PackageRuntimeModule = Record<string, unknown>;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -42,15 +38,11 @@ function isMissingRuntimeModuleError(error: unknown, modulePath: string): boolea
 }
 
 function resolvePackageRootCandidates(): string[] {
-  const candidates: string[] = [];
   const envRoot = process.env[PM_PACKAGE_ROOT_ENV];
-  if (typeof envRoot === "string" && envRoot.trim().length > 0) {
-    candidates.push(path.resolve(envRoot.trim()));
-  }
+  const candidates = typeof envRoot === "string" && envRoot.trim().length > 0 ? [path.resolve(envRoot.trim())] : [];
   const argvEntry = typeof process.argv[1] === "string" ? process.argv[1].trim() : "";
   if (argvEntry.length > 0) {
-    const resolvedEntry = path.resolve(argvEntry);
-    const entryDir = path.dirname(resolvedEntry);
+    const entryDir = path.dirname(path.resolve(argvEntry));
     candidates.push(path.resolve(entryDir, ".."));
     candidates.push(path.resolve(entryDir, "../.."));
     candidates.push(path.resolve(entryDir, "../../.."));
@@ -58,41 +50,36 @@ function resolvePackageRootCandidates(): string[] {
   return [...new Set(candidates)];
 }
 
-export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
-  const attempted: string[] = [];
-  for (const packageRoot of resolvePackageRootCandidates()) {
-    const modulePaths = [
-      path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.ts"),
-      path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.ts"),
-    ];
-    for (const modulePath of modulePaths) {
-      attempted.push(modulePath);
-      if (!existsSync(modulePath)) {
-        continue;
-      }
-      try {
-        return await import(pathToFileURL(modulePath).href) as PackageRuntimeModule;
-      } catch (error: unknown) {
-        if (isMissingRuntimeModuleError(error, modulePath)) {
-          continue;
-        }
-        throw error;
-      }
+function runtimePaths(packageRoot: string): string[] {
+  return [
+    path.join(packageRoot, ".agents", "pm", "extensions", EXTENSION_NAME, "runtime.ts"),
+    path.join(packageRoot, "packages", PACKAGE_NAME, "extensions", EXTENSION_NAME, "runtime.ts"),
+  ];
+}
+
+async function tryRuntime(modulePath: string, attempted: string[]): Promise<PackageRuntimeModule | undefined> {
+  attempted.push(modulePath);
+  if (!existsSync(modulePath)) {
+    return undefined;
+  }
+  try {
+    return await import(pathToFileURL(modulePath).href) as PackageRuntimeModule;
+  } catch (error: unknown) {
+    if (isMissingRuntimeModuleError(error, modulePath)) {
+      return undefined;
     }
+    throw error;
   }
+}
 
-  const localRuntimePath = path.join(CURRENT_EXTENSION_ROOT, "runtime.ts");
-  attempted.push(localRuntimePath);
-  if (existsSync(localRuntimePath)) {
-    try {
-      return await import(pathToFileURL(localRuntimePath).href) as PackageRuntimeModule;
-    } catch (error: unknown) {
-      if (!isMissingRuntimeModuleError(error, localRuntimePath)) {
-        throw error;
-      }
+export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
+  const attempted: string[] = [];
+  for (const modulePath of [...resolvePackageRootCandidates().flatMap(runtimePaths), path.join(CURRENT_EXTENSION_ROOT, "runtime.ts")]) {
+    const loaded = await tryRuntime(modulePath, attempted);
+    if (loaded) {
+      return loaded;
     }
   }
-
   throw new Error(
     `Unable to resolve packaged ${DIAGNOSTIC_NAME} extension runtime module. ` +
       `Tried: ${attempted.join(", ")}. Ensure the installed extension includes runtime.ts or PM_CLI_PACKAGE_ROOT points to an installed pm package root.`,