@unbrained/pm-cli 2026.7.2 → 2026.7.3

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.3",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "author": "unbrained",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
-  "description": "Native pm CLI integration for Claude Code — 26 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full 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 (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
+  "version": "1.4.1",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/README.md

@@ -6,7 +6,7 @@ Native pm CLI integration for Claude Code. Use pm project management tools direc
 
 | Component | What it provides |
 |-----------|----------------|
-| **26 MCP tools** | Full pm surface: context, search, list, get, create, copy, focus, update, claim, release, close, comments, files, docs, notes, learnings, deps, test, validate, health, contracts, plan, append, schema, config + `pm_run` for everything else |
+| **28 MCP tools** | Full pm surface: next, context, search, list, get, create, copy, focus, update, claim, release, close, comments, files, docs, notes, learnings, deps, test, validate, health, contracts, plan, append, schema, config, profile + `pm_run` for everything else |
 | **5 skills** | `pm-workflow`, `pm-developer`, `pm-release`, `pm-audit`, `pm-planner` — auto-loaded as Claude Code skills |
 | **14 slash commands** | Full lifecycle coverage — status, start, close, triage, audit, search, new, list, calendar, developer, planner, release, workflow, init |
 | **4 subagents** | `pm-coordinator` (batch/multi-item), `pm-triage-agent` (duplicate-safe item creation), `pm-verification-agent` (evidence + close readiness), and `pm-delivery-chain` (orchestrated delivery) |
@@ -29,7 +29,7 @@ claude plugin marketplace add /path/to/pm-cli
 # claude plugin marketplace add unbraind/pm-cli
 ```
 
-This installs all 26 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step. (`pm-claude` is the plugin name; `pm` is the marketplace name from `marketplace.json`.)
+This installs all 28 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid TUI tracking, and the session hook in one step. (`pm-claude` is the plugin name; `pm` is the marketplace name from `marketplace.json`.)
 
 ### Option B: Global MCP server via Claude Code CLI (MCP tools only)
 
@@ -37,7 +37,7 @@ This installs all 26 MCP tools, 5 skills, 14 slash commands, 4 subagents, hybrid
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-This gives you the 26 MCP tools but not the skills, slash commands, or session hook.
+This gives you the 28 MCP tools but not the skills, slash commands, or session hook.
 
 ### Option C: Direct `.mcp.json` (project-scoped MCP only)
 
@@ -139,12 +139,14 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 
 | Tool | Purpose |
 |------|---------|
+| `pm_next` | Pick the next actionable item |
 | `pm_context` | Active work snapshot |
 | `pm_search` | Keyword/semantic/hybrid search |
 | `pm_list` | Filtered item list |
 | `pm_get` | Single item detail |
 | `pm_create` | Create new item |
 | `pm_copy` | Copy item into a new id |
+| `pm_focus` | Set or clear the focused item |
 | `pm_update` | Update metadata |
 | `pm_append` | Append text to item body |
 | `pm_claim` | Claim for active work |
@@ -162,6 +164,7 @@ Spawn pm-triage-agent to set up the pm item for: add OAuth2 login support
 | `pm_contracts` | Inspect command contracts |
 | `pm_schema` | Manage custom item types/statuses |
 | `pm_config` | Read or write settings keys |
+| `pm_profile` | List/show/apply project profiles |
 | `pm_plan` | Manage durable Plan workflows |
 
 ### General tool

package/plugins/pm-claude/commands/pm-init.md

@@ -47,7 +47,7 @@ Initialize pm project tracking using native MCP tools. Argument: `$ARGUMENTS` (o
    - pm initialized at `.agents/pm/`
    - guidance mode defaults to `ask` (TTY prompt only); use `agentGuidance=add|skip|status` in `pm_run` options for deterministic behavior
    - Available slash commands: `/pm-status`, `/pm-new`, `/pm-start-task`, `/pm-close-task`, `/pm-list`, `/pm-search`, `/pm-triage`, `/pm-calendar`, `/pm-developer`, `/pm-planner`, `/pm-release`, `/pm-audit`, `/pm-workflow`
-   - All 26 MCP tools available: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_copy`, `pm_focus`, `pm_update`, `pm_append`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_notes`, `pm_learnings`, `pm_deps`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_schema`, `pm_config`, `pm_plan`, `pm_run`
+   - All 28 MCP tools available: `pm_next`, `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_copy`, `pm_focus`, `pm_update`, `pm_append`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_notes`, `pm_learnings`, `pm_deps`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_schema`, `pm_config`, `pm_profile`, `pm_plan`, `pm_run`
    - Next: use `/pm-new <title>` to create your first item, or `/pm-status` to see the tracker state
 
 If initialization fails, report the error and suggest running `pm init` manually in the terminal.

package/dist/cli-bundle/chunks/activity-WEIEMM73.js

@@ -1,16 +0,0 @@
-import {
-  _testOnly,
-  runActivity
-} from "./chunk-GFMSLORL.js";
-import "./chunk-A6VOGKBA.js";
-import "./chunk-N2JSWVWG.js";
-import "./chunk-JMK5GCK2.js";
-import "./chunk-JXAUVO6X.js";
-import "./chunk-IEEJQCZ4.js";
-import "./chunk-AIAIXG7I.js";
-import "./chunk-7NSPKJUS.js";
-export {
-  _testOnly,
-  runActivity
-};
-//# sourceMappingURL=activity-WEIEMM73.js.map