@unbrained/pm-cli 2026.5.10 → 2026.5.11

package/docs/MIGRATION_CLI_SIMPLIFICATION.md

@@ -0,0 +1,64 @@
+# CLI Simplification Migration (Conservative Full-Surface Pass)
+
+This note documents behavioral and output-shape changes introduced in the conservative CLI simplification pass.
+
+## What Changed
+
+### 1) Command invocation normalization before Commander parse
+
+`pm` now normalizes invocation tokens before Commander parses them:
+
+- long-flag shape normalization (`--foo_bar` / camel variants -> canonical kebab flags)
+- high-confidence typo normalization for long flags
+- `key=value` / `key:value` promotion into canonical `--flag value` tokens when unambiguous
+- legacy `pm extension <action>` shorthand normalization to explicit action flags
+
+Normalization runs across command families and preserves a normalization trace for diagnostics and recovery.
+
+### 2) Setup-agnostic PM root discovery
+
+`resolvePmRoot()` precedence is now:
+
+1. explicit `--path`
+2. `PM_PATH`
+3. upward discovery of initialized `.agents/pm` roots (must contain `settings.json`)
+4. local default (`<cwd>/.agents/pm`)
+
+If you need the old local-only behavior from nested directories, pass an explicit path (`--path .agents/pm`).
+
+### 3) Structured recovery bundles in CLI error output
+
+Error payloads now include optional `recovery` metadata in text and JSON guidance surfaces:
+
+- `attempted_command`
+- `normalized_args`
+- `provided_fields`
+- `missing`
+- `suggested_retry`
+
+Automation should read this bundle for deterministic retries instead of rebuilding retries from free-form error text.
+
+### 4) Legacy `none`/`null` compatibility in create/update
+
+For deterministic compatibility:
+
+- scalar `none` / `null` values on unset-capable fields are reinterpreted as `--unset <field>`
+- repeatable `none` / `null` values are reinterpreted as their matching `--clear-*` action
+- mixed legacy clear token + concrete repeatable payloads remain rejected (ambiguous input)
+
+## Migration Guidance for Automation
+
+- **Prefer contracts first**: keep using `pm contracts --json` and command-scoped flag contracts.
+- **Consume `recovery` directly**: treat `recovery.suggested_retry` as first-choice replay command.
+- **Do not hardcode old error envelopes**: parsers should tolerate additional fields (`recovery`) and richer guidance text.
+- **Avoid relying on local cwd-only root resolution**: pass `--path` explicitly when wrappers need fixed data roots.
+- **Update none/null assumptions**: if your tests expected hard failures for pure `none`/`null` clear intents, update them to expect deterministic clear/unset behavior.
+
+## Verification Checklist
+
+- `tests/unit/bootstrap-args.spec.ts`
+- `tests/unit/store-paths.spec.ts`
+- `tests/integration/help-runtime.spec.ts`
+- `tests/unit/create-command.spec.ts`
+- `tests/unit/update-command.spec.ts`
+

package/docs/PI_PACKAGE.md

@@ -1,8 +1,75 @@
-# Pi Native Package
+# Pi Native Package & Claude Code Plugin
 
-pm-cli ships an official Pi package so Pi can use pm through a native extension instead of shelling out to the `pm` CLI.
+pm-cli ships both an official Pi package and a Claude Code plugin so AI coding agents can use pm through native integrations instead of shelling out to the `pm` CLI.
 
-## Install
+## Claude Code Plugin
+
+The Claude Code plugin (`plugins/pm-cli-claude/`) provides full native pm integration for Claude Code without any CLI dependency.
+
+### Install
+
+```
+/plugin install pm-cli@pm
+```
+
+Both `pm` and `pm-cli` marketplace IDs work:
+
+```
+/plugin install pm-cli@pm      # canonical
+/plugin install pm-cli@pm-cli  # legacy alias
+```
+
+To add the marketplace first (local checkout):
+
+```bash
+claude plugin marketplace add /path/to/pm-cli
+```
+
+After npm publish, the marketplace will be available via GitHub:
+
+```bash
+claude plugin marketplace add unbraind/pm-cli
+```
+
+### Plugin Components
+
+| Component | Path | What it provides |
+|-----------|------|-----------------|
+| MCP server | `scripts/pm-mcp-server.mjs` | 18 native MCP tools |
+| Skills | `skills/` | 5 workflow skills auto-loaded in Claude Code |
+| Commands | `commands/` | 14 slash commands |
+| Agents | `agents/` | 3 subagents + 1 delivery chain |
+| Hooks | `hooks/` | Session-start context injection |
+
+### MCP Tools (18)
+
+Narrow tools: `pm_context`, `pm_search`, `pm_list`, `pm_get`, `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`, `pm_comments`, `pm_files`, `pm_docs`, `pm_test`, `pm_validate`, `pm_health`, `pm_contracts`, `pm_guide`
+
+General tool: `pm_run` (with explicit `action` for everything else)
+
+### Subagents (4)
+
+| Agent | Description |
+|-------|-------------|
+| `pm-coordinator` | Multi-item batch coordination |
+| `pm-triage-agent` | Duplicate-safe item creation with lineage |
+| `pm-verification-agent` | Evidence collection and close readiness |
+| `pm-delivery-chain` | Full triage → implement → verify orchestration |
+
+### Session Hook
+
+The session-start hook runs natively:
+1. Walks up from plugin root to find `dist/pi/native.js` in a repo checkout
+2. Falls back to `npx @unbrained/pm-cli` if no local dist
+3. No `pm` CLI global install required in either path
+
+---
+
+## Pi Native Package
+
+The Pi package at `.pi/` exposes pm through Pi's native extension API.
+
+### Install
 
 After the package is published:
 
@@ -10,8 +77,6 @@ After the package is published:
 pi install npm:@unbrained/pm-cli
 ```
 
-If you install an unscoped npm alias, use the same Pi syntax, for example `pi install npm:pm-cli`. The published package in this repository is `@unbrained/pm-cli`.
-
 From a local checkout:
 
 ```bash
@@ -23,7 +88,7 @@ pi --no-extensions -e .
 
 `pnpm build` is required for local checkouts because the Pi extension imports the compiled native integration from `dist/pi/native.js`.
 
-## Package Resources
+### Package Resources
 
 The root `package.json` declares the Pi manifest:
 
@@ -34,10 +99,12 @@ The root `package.json` declares the Pi manifest:
 The extension registers:
 
 - native `pm` tool using pm command modules directly, not the `pm` shell command
-- `/pm-context`, `/pm-start`, `/pm-close`, and `/pm-actions` helper commands
-- status footer entry `pm native`
+- custom TUI rendering for pm tool calls/results (context, list/search, item details, history/activity)
+- `/pm-context`, `/pm-board`, `/pm-item`, `/pm-history`, `/pm-start`, `/pm-close`, `/pm-actions`, and `/pm-workflows` helper commands
+- `@pm-...` item autocomplete layered on top of Pi's editor completion
+- footer status and a small below-editor widget (`pm native ready`) in interactive mode
 
-## Native Tool Usage
+### Native Tool Usage
 
 Use the Pi `pm` tool with an `action` field. Examples:
 
@@ -51,6 +118,24 @@ Use the Pi `pm` tool with an `action` field. Examples:
 
 For real project tracking, leave `path` unset. For tests, set `path` to a sandbox pm root and isolate `PM_GLOBAL_PATH`.
 
+### Pi TUI Commands
+
+```text
+/pm-board [limit]        # context dashboard with active items
+/pm-item <pm-id>         # item details and recent comments
+/pm-history <pm-id>      # item history panel
+/pm-actions              # installed native action list
+/pm-workflows            # suggested native pm workflows
+```
+
+### Pi Skills and Subagents
+
+- Skills: `pm-native`, `pm-release`
+- Prompt template: `/pm-workflow`
+- Subagent files: `.pi/agents/pm-triage-agent.md`, `.pi/agents/pm-verification-agent.md`, `.pi/chains/pm-native-delivery.chain.md`
+
+---
+
 ## Supported Surface
 
-The native integration covers the core pm action set exposed by the SDK contracts: init/config/extensions, item creation and lifecycle, list/search/context/calendar/activity, files/docs/deps/tests, validation/health/gc/contracts, templates, test-runs, and guide workflows.
+Both integrations cover the core pm action set: init/config/extensions, item creation and lifecycle, list/search/context/calendar/activity, files/docs/deps/tests, validation/health/gc/contracts, templates, test-runs, guide workflows, bundled beads/todos import/export, and lifecycle shortcuts (`start-task`, `pause-task`, `close-task`).

package/docs/SDK.md

@@ -1,5 +1,429 @@
 # SDK
 
+The supported programmatic surface is `@unbrained/pm-cli/sdk`.
+
+Use this package for extension authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+## Core Exports
+
+### Extension authoring
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+- `EXTENSION_TRUST_MODES`
+- `EXTENSION_SANDBOX_PROFILES`
+
+### Command and action contracts
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+### Runtime contract constants
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
+- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
+
+### Type guards
+
+- `isPmToolAction`
+- `isPmExtensionCapabilityContract`
+- `isPmExtensionServiceNameContract`
+- `isPmExtensionPolicyModeContract`
+- `isPmExtensionPolicySurfaceContract`
+
+## Capability Mapping
+
+- `commands` -> `registerCommand`
+- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
+- `importers` -> `registerImporter`, `registerExporter`
+- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
+- `hooks` -> `api.hooks.*`
+- `parser` -> `registerParser`
+- `preflight` -> `registerPreflight`
+- `services` -> `registerService`
+- `renderers` -> `registerRenderer`
+
+## Extension Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release-readiness diagnostics.",
+      intent: "Produce deterministic gate payloads for CI.",
+      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        strict: context.options.strict === true,
+      }),
+    });
+  },
+});
+```
+
+## Contracts-First Automation
+
+Use runtime contracts for extension-aware schemas:
+
+```bash
+pm contracts --json
+pm contracts --schema-only --json
+pm contracts --command extension --flags-only --json
+pm contracts --action create --schema-only --json
+```
+
+Minimal script pattern:
+
+```ts
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+import { spawnSync } from "node:child_process";
+
+const action = "extension-reload";
+if (!isPmToolAction(action)) throw new Error("Unsupported action");
+const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
+console.log(contract.required, contract.optional);
+
+const result = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
+if (result.status !== 0) throw new Error(result.stderr);
+```
+
+## Compatibility Metadata
+
+`pm contracts --json` includes compatibility metadata for extension integrations:
+
+- `extension_contracts.trust_modes`
+- `extension_contracts.sandbox_profiles`
+- `extension_contracts.manifest_versions`
+- `extension_contracts.compatibility`
+- `action_availability[].policy_state`
+
+Current compatibility model:
+
+- manifest current: `v2`
+- supported previous: `v1`
+- strategy: `versioned_breaking`
+
+## Runnable Examples
+
+- `docs/examples/sdk-contract-consumer/`
+- `docs/examples/sdk-app-embedding/`
+- `docs/examples/ci/`
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/CLAUDE_CODE_PLUGIN.md`
+# SDK
+
+The supported programmatic surface is `@unbrained/pm-cli/sdk`.
+
+Use this for:
+
+- extension authoring (`defineExtension`)
+- command/action schema discovery (`PM_TOOL_PARAMETERS_SCHEMA`)
+- runtime action contracts (`PM_TOOL_ACTION_PARAMETER_CONTRACTS`)
+- capability/policy/trust/sandbox contract constants
+
+Do not import private `src/core/...` modules from external integrations.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+## Key Exports
+
+### Extension Authoring
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+- `EXTENSION_TRUST_MODES`
+- `EXTENSION_SANDBOX_PROFILES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_CAPABILITY_CONTRACT_VERSION`
+- `EXTENSION_CAPABILITY_LEGACY_ALIASES`
+
+### Command/Action Contracts
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+### Extension Runtime Contract Constants
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+- `PM_EXTENSION_TRUST_MODE_CONTRACTS`
+- `PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS`
+
+### Type Guards
+
+- `isPmToolAction`
+- `isPmExtensionCapabilityContract`
+- `isPmExtensionServiceNameContract`
+- `isPmExtensionPolicyModeContract`
+- `isPmExtensionPolicySurfaceContract`
+
+## Extension Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release-readiness diagnostics.",
+      intent: "Produce deterministic gate payloads for CI.",
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+      }),
+    });
+  },
+});
+```
+
+## Contracts-First Automation Pattern
+
+```ts
+import { PM_TOOL_ACTION_PARAMETER_CONTRACTS, isPmToolAction } from "@unbrained/pm-cli/sdk";
+import { spawnSync } from "node:child_process";
+
+const action = "extension-reload";
+if (!isPmToolAction(action)) throw new Error("Unsupported action");
+const contract = PM_TOOL_ACTION_PARAMETER_CONTRACTS[action];
+console.log(contract.required, contract.optional);
+
+const contracts = spawnSync("pm", ["contracts", "--json"], { encoding: "utf8" });
+if (contracts.status !== 0) throw new Error(contracts.stderr);
+```
+
+## Runtime Metadata Added For v2
+
+`pm contracts --json` now includes richer extension metadata:
+
+- `extension_contracts.trust_modes`
+- `extension_contracts.sandbox_profiles`
+- `extension_contracts.manifest_versions`
+- `extension_contracts.compatibility`
+- `action_availability[].policy_state` for extension-backed actions
+
+Use these fields to gate CI and to route compatibility behavior in embedded runtimes.
+
+## Versioned-Breaking Compatibility
+
+Current contract compatibility model:
+
+- `manifest` current: `v2`
+- supported previous: `v1`
+- strategy: `versioned_breaking`
+
+Recommended migration flow:
+
+1. read runtime contracts (`pm contracts --json`)
+2. branch behavior by compatibility metadata
+3. migrate manifests/policy to v2
+4. enforce trust/sandbox policy gates in CI
+
+## Runnable Examples
+
+- contracts consumer: `docs/examples/sdk-contract-consumer/`
+- app embedding runner: `docs/examples/sdk-app-embedding/`
+- CI gates: `docs/examples/ci/`
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/CLAUDE_CODE_PLUGIN.md`
+# SDK
+
+The stable integration surface is `@unbrained/pm-cli/sdk`. Use it for extension authoring, action/flag contract discovery, and deterministic app/CI automation.
+
+## Install
+
+```bash
+npm install @unbrained/pm-cli
+```
+
+```ts
+import {
+  defineExtension,
+  EXTENSION_CAPABILITIES,
+  EXTENSION_POLICY_MODES,
+  EXTENSION_POLICY_SURFACES,
+  PM_TOOL_ACTIONS,
+  PM_TOOL_PARAMETERS_SCHEMA,
+  PM_TOOL_ACTION_PARAMETER_CONTRACTS,
+  PM_EXTENSION_CAPABILITY_CONTRACTS,
+  PM_EXTENSION_SERVICE_NAME_CONTRACTS,
+  PM_EXTENSION_POLICY_MODE_CONTRACTS,
+  PM_EXTENSION_POLICY_SURFACE_CONTRACTS,
+  isPmToolAction,
+  isPmExtensionCapabilityContract,
+} from "@unbrained/pm-cli/sdk";
+```
+
+## What Is Exported
+
+Core authoring exports:
+
+- `defineExtension`
+- `EXTENSION_CAPABILITIES`
+- `EXTENSION_CAPABILITY_CONTRACT`
+- `EXTENSION_POLICY_MODES`
+- `EXTENSION_POLICY_SURFACES`
+
+Command/action contract exports:
+
+- `PM_CORE_COMMAND_NAMES`
+- `PM_TOOL_ACTIONS`
+- `PM_TOOL_PARAMETERS_SCHEMA`
+- `PM_PI_TOOL_PARAMETERS_SCHEMA`
+- `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
+
+Extension runtime contract exports:
+
+- `PM_EXTENSION_CAPABILITY_CONTRACTS`
+- `PM_EXTENSION_SERVICE_NAME_CONTRACTS`
+- `PM_EXTENSION_POLICY_MODE_CONTRACTS`
+- `PM_EXTENSION_POLICY_SURFACE_CONTRACTS`
+
+Type guards:
+
+- `isPmToolAction(value)`
+- `isPmExtensionCapabilityContract(value)`
+- `isPmExtensionServiceNameContract(value)`
+- `isPmExtensionPolicyModeContract(value)`
+- `isPmExtensionPolicySurfaceContract(value)`
+
+## Capability Mapping
+
+- `commands` -> `registerCommand`
+- `schema` -> `registerFlags`, `registerItemFields`, `registerItemTypes`, `registerMigration`
+- `importers` -> `registerImporter`, `registerExporter`
+- `search` -> `registerSearchProvider`, `registerVectorStoreAdapter`
+- `hooks` -> `api.hooks.*`
+- `parser` -> `registerParser`
+- `preflight` -> `registerPreflight`
+- `services` -> `registerService`
+- `renderers` -> `registerRenderer`
+
+## Extension Authoring Example
+
+```ts
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerCommand({
+      name: "release audit",
+      action: "release-audit",
+      description: "Collect release readiness diagnostics.",
+      intent: "provide deterministic audit payloads for CI gates",
+      examples: ["pm release audit --strict"],
+      failure_hints: ["Run pm extension --doctor --detail deep --trace on activation failures."],
+      flags: [{ long: "--strict", description: "Enable strict gate mode." }],
+      run: async (context) => ({
+        ok: true,
+        command: context.command,
+        strict: context.options.strict === true,
+      }),
+    });
+  },
+});
+```
+
+## Programmatic Contracts (App/Script)
+
+Use runtime `pm contracts` for extension-aware schemas:
+
+```bash
+pm contracts --json
+pm contracts --schema-only --json
+pm contracts --command extension --flags-only --json
+pm contracts --action create --schema-only --json
+```
+
+The result includes:
+
+- `actions`: runtime-invocable action list
+- `action_availability`: invocable/disabled reasons
+- `schema`: strict action-scoped JSON schema
+- `command_flags`: merged core + extension + runtime field flags
+- `extension_contracts`: capabilities/services/policy mode/surface contract metadata
+
+## Robust Script Pattern
+
+See runnable example: `docs/examples/sdk-contract-consumer/inspect-contracts.mjs`.
+
+Minimal pattern:
+
+1. Read contracts JSON.
+2. Validate action exists in `actions`.
+3. Validate required fields with `PM_TOOL_ACTION_PARAMETER_CONTRACTS`.
+4. Execute the action only after preflight passes.
+
+## CI/CD Pattern
+
+Recommended gate sequence:
+
+```bash
+pnpm build
+pm contracts --schema-only --json > /tmp/pm-contracts.json
+pm extension --doctor --project --detail summary --strict-exit
+node scripts/run-tests.mjs test -- tests/unit/contracts-command.spec.ts
+node scripts/run-tests.mjs coverage
+```
+
+Reference workflow file:
+
+- `docs/examples/ci/github-actions-pm-extension-gate.yml`
+
+## Pi / Tooling Compatibility
+
+For provider-safe schemas, use `PM_PI_TOOL_PARAMETERS_SCHEMA`. It is flat, non-`oneOf`, and designed for tool providers that reject advanced schema constructs.
+
+The bundled Pi wrapper (`.pi/extensions/pm-cli/index.js`) consumes this schema directly to reduce contract drift.
+
+## Related Docs
+
+- `docs/EXTENSIONS.md`
+- `docs/examples/starter-extension/README.md`
+- `docs/examples/sdk-contract-consumer/README.md`
+# SDK
+
 The public SDK is exported from `@unbrained/pm-cli/sdk`. Use it for extension authoring and command-contract introspection. Do not import internal `src/core/...` modules from extensions.
 
 ## Agent Quick Context
@@ -167,6 +591,22 @@ pm contracts --action create --schema-only --json
 
 Use the runtime command because active extensions can add command/action metadata.
 
+## CLI Simplification Migration
+
+The conservative full-surface simplification pass updated invocation parsing and error envelopes. Integration details are documented in:
+
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
+
+For SDK and automation consumers, the key runtime change is the optional `recovery` object in CLI usage/error JSON payloads:
+
+- `attempted_command`
+- `normalized_args`
+- `provided_fields`
+- `missing`
+- `suggested_retry`
+
+Treat `recovery.suggested_retry` as the first-choice deterministic replay command when present.
+
 ## Authoring Pattern
 
 - Keep handlers deterministic and JSON-like.
@@ -179,5 +619,6 @@ Use the runtime command because active extensions can add command/action metadat
 ## Related Docs
 
 - [Extensions](EXTENSIONS.md)
+- [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md)
 - [Architecture](ARCHITECTURE.md)
 - [starter extension](examples/starter-extension/README.md)