@unbrained/pm-cli 2026.7.11 → 2026.7.12

package/docs/CODEX_PLUGIN.md

@@ -2,6 +2,11 @@
 
 pm-cli ships a repo-local Codex plugin at [`plugins/pm-codex`](../plugins/pm-codex/README.md).
 
+It is a real Codex plugin package: the repo marketplace installs it and Codex registers its skills and bundled
+MCP server. It is not yet a self-contained cached runtime or an Apps SDK-backed ChatGPT app. The official-source
+audit, verified gaps, and phased remediation plan are documented in
+[Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md).
+
 ## Install From This Repo
 
 ```bash
@@ -18,7 +23,7 @@ The canonical tool, skill, command, and safety inventory lives in the plugin REA
 
 Keep this page as the public docs router so the MCP tool/action list has one maintained source.
 
-## Native MCP Notes
+## Current MCP Runtime Note
 
 The plugin launcher uses the local repository build when `dist/mcp/server.js` is present. When the plugin is cached outside the repo, it falls back to:
 
@@ -28,6 +33,11 @@ npx -y --package=@unbrained/pm-cli@latest pm-mcp
 
 The fallback starts the package MCP server, not the `pm` CLI command. Tool calls import pm command modules and return JSON-compatible structured results.
 
+This is current behavior, not the target distribution contract. A normal cached install has no repository
+`dist/` ancestor, so it depends on npm availability and can run a newer server than the installed plugin. Track
+the self-contained, version-coherent runtime work under
+[pm-95d7](../.agents/pm/features/pm-95d7.toon).
+
 ## Safety
 
 For real repository tracking, leave `path` unset so pm uses the repository `.agents/pm` root. For tests, use a sandbox `cwd` or `path` and isolate `PM_GLOBAL_PATH`.

package/docs/COMMANDS.md

@@ -101,7 +101,9 @@ pm dedupe-audit --mode parent_scope --limit 20
 pm dedupe-merge --keep pm-canonical --close pm-duplicate --dry-run
 ```
 
-Use `pm next` when the only question is "what should I work on now?" It computes dependency-aware readiness, keeps dangling dependency ids blocked until repaired, and combines lifecycle-blocked plus graph-blocked work in the companion queue. The `recommended` projection is excluded from the `ready` tail, while foreign-owned in-progress work is summarized under `held_by_others`. Use `pm claim --next` to atomically select and claim caller-available work with bounded conflict retry. Scope with `--parent`, cap rows with `--limit`/`--blocked-limit`, or use `--ready-only` for the tightest projection.
+Use `pm next` when the only question is "what should I work on now?" It computes dependency-aware readiness, keeps dangling dependency ids blocked until repaired, and combines lifecycle-blocked plus graph-blocked work in the companion queue. The `recommended` projection is excluded from the `ready` tail; every actionable row carries its one-based `rank`, and the tail preserves the exact recommendation order. Foreign-owned in-progress work is summarized under `held_by_others`. Human-gated `Decision` records remain visible under `decision_needed` but are excluded from agent recommendations by default.
+
+Use `pm claim --next` to atomically select and claim caller-available work with bounded conflict retry. It accepts the same `--type`, `--tag`, `--priority`, `--assignee-filter`, `--parent`, `--sprint`, and `--release` candidate filters as `pm next`; `--max-attempts` bounds the ranked race-loss walk (default 10, maximum 100). With `--if-available`, exhaustion is a successful empty result (`available: false`, `item: null`, `skipped: true`) instead of an exception, which supports contention-tolerant worker loops. Pass `--include-decisions` only for a coordinated maintainer lane authorized to claim human-gated decisions. Scope snapshots with `--parent`, cap rows with `--limit`/`--blocked-limit`, or use `--ready-only` for the tightest projection.
 
 ```bash
 pm next                                 # recommend the next action + ready/blocked queues

package/docs/README.md

@@ -24,6 +24,7 @@ pm guide release --json
 | Coding agent | [Agent Guide](AGENT_GUIDE.md) | [Configuration](CONFIGURATION.md), then command help |
 | Maintainer | [Contributing](../CONTRIBUTING.md) | [Testing](TESTING.md), [Releasing](RELEASING.md), [Architecture](ARCHITECTURE.md) |
 | Package author | [Packages and Extensions](EXTENSIONS.md) | [SDK](SDK.md), [starter extension](examples/starter-extension/README.md) |
+| Codex or ChatGPT plugin implementer | [Codex Plugin](CODEX_PLUGIN.md) | [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) |
 | Codex user | [Codex Plugin](CODEX_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Claude Code user | [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) | [Agent Guide](AGENT_GUIDE.md), then [Command Reference](COMMANDS.md) |
 | Machine client | `pm contracts --json` | [Command Reference](COMMANDS.md#machine-contracts), optionally `pm install guide-shell --project && pm guide commands` |
@@ -42,6 +43,8 @@ pm guide release --json
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
+- [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) - official-source
+  research, current-state audit, target architectures, security, testing, and phased remediation plan.
 - [Claude Code Plugin](CLAUDE_CODE_PLUGIN.md) - native Claude Code plugin architecture and install flow.
 - [CLI Simplification Migration](MIGRATION_CLI_SIMPLIFICATION.md) - root discovery (`--pm-path`), recovery bundles, and clear/unset semantics for automation maintainers.
 - [Releasing](RELEASING.md) - maintainer release checklist and failure handling.

package/docs/SDK.md

@@ -112,9 +112,12 @@ Command/action contract exports:
 - Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, and `append`
 - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
 - Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
+- Workspace-scaffold primitives: `ensurePmGitignore` and `getPmGitignoreBlock` let custom tools apply the same idempotent runtime/search cache policy as `pm init` without importing CLI internals.
 - Customization primitive option/result contracts: `InitCommandOptions` / `InitResult`, `ConfigCommandOptions` / `ConfigResult`, `SchemaSubcommand` / `SchemaResult` / `SchemaInspectResult`, `SchemaListResult`, `SchemaShowResult`, `SchemaAddTypeResult`, `SchemaRemoveTypeResult`, `SchemaAddStatusResult`, `SchemaRemoveStatusResult`, `SchemaAddFieldResult`, `SchemaRemoveFieldResult`, `SchemaListFieldsResult`, `SchemaShowFieldResult`, `SchemaApplyPresetResult`, `SchemaAddTypeInferResult`, `SchemaShowStatusResult`, `ProfileSubcommand` / `ProfileResult`, `ProfileListResult`, `ProfileShowResult`, `ProfileApplyResult`, `ProfileLintResult`
 - Typed governance and maintenance primitives on `PmClient`: `validate`, `health`, and `gc`
 - Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`
+- Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
+- Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
 - Lifecycle primitive option/result contracts: `ExtensionCommandOptions` / `ExtensionCommandResult`, `PackageCommandOptions` / `PackageCommandResult`, `UpgradeCommandOptions` / `UpgradeResult`
 - `PM_CORE_COMMAND_NAMES`
@@ -123,6 +126,35 @@ Command/action contract exports:
 - `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+### Plan workflows
+
+Custom tools can manage durable plans without shelling out or importing CLI internals. The typed façade uses the same engine and result envelopes as `pm plan` and MCP `pm_plan`:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot, author: "planning-agent" });
+await pm.schemaAddField("acceptance_owner", {
+  type: "string",
+  requiredOnCreate: true,
+  requiredTypes: ["Task"],
+});
+const created = await pm.planCreate({
+  title: "Ship governed workflow",
+  step: ["Implement", "Verify"],
+});
+await pm.planUpdateStep(created.plan.id, "plan-step-001", {
+  stepStatus: "in_progress",
+});
+const result = await pm.planMaterialize(created.plan.id, {
+  steps: "all",
+  materializeType: "Task",
+  field: ["acceptance_owner=planning-agent"],
+});
+```
+
+`field` is repeatable and forwards `name=value` pairs through normal schema-aware create validation for every materialized child. Required-on-create fields remain mandatory. Each `materialized` entry includes `id`, `title`, `type`, `parent`, `tags`, and `from_step`, so an agent can confirm the created work without extra `get` calls.
+
 Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 
 - `createExtensionTestHarness`
@@ -206,7 +238,7 @@ is the "invoke" verb that completes the package-author testing loop —
 `activateExtensionForTest` → `assertRegisteredCommandContract` → **run** →
 `deactivateExtensionForTest`. It dispatches a registered command handler through
 pm's real engine and returns the `CommandHandlerResult`, so a test can assert
-*behavior* (`result.result`) rather than only that the command is wired. The
+_behavior_ (`result.result`) rather than only that the command is wired. The
 `CommandHandlerContext` is built with agent-safe global defaults
 (`{ json: true, quiet: true, noPager: true }`) that callers may override. A clean
 run yields `{ handled: true, result, warnings: [] }`; a handler that throws a
@@ -243,7 +275,7 @@ Each override helper guards that a matching override is registered for the targe
 (command / format / service), so a typo surfaces as a descriptive error rather
 than a silent `overridden: false` / `handled: false`.
 
-The *executable registration* surfaces — search providers, vector store
+The _executable registration_ surfaces — search providers, vector store
 adapters, schema migrations, importers, and exporters — also have invoke helpers,
 so every executable register\* method has both an `assertRegistered*` and a
 `runRegistered*ForTest` counterpart. Each exercises the real registered behavior,
@@ -291,7 +323,7 @@ silent no-op. All invoke helpers are `async`, so a test always `await`s them.
 `describeExtensionActivation(activation, { extensionName })` is the **describe**
 (enumerate-all) verb that complements the `assertRegistered*` (verify-one) and
 `runRegistered*ForTest` (invoke-one) helpers. The activation result already
-carries per-surface *counts*; this returns the *names*. It walks every
+carries per-surface _counts_; this returns the _names_. It walks every
 sub-registry once and returns a flat `ExtensionActivationSummary` whose arrays
 are de-duplicated and locale-sorted (except `hooks`, emitted in canonical
 lifecycle order to mirror `hook_counts`) of every registered surface's
@@ -346,9 +378,15 @@ default `2`; section headings render one level deeper) control nesting, and
 empty ones.
 
 ```ts
-import { describeExtensionBlueprint, renderExtensionSurfaceMarkdown } from "@unbrained/pm-cli/sdk";
+import {
+  describeExtensionBlueprint,
+  renderExtensionSurfaceMarkdown,
+} from "@unbrained/pm-cli/sdk";
 
-const reference = renderExtensionSurfaceMarkdown(describeExtensionBlueprint(blueprint), { title: "my-pkg", headingLevel: 2 });
+const reference = renderExtensionSurfaceMarkdown(
+  describeExtensionBlueprint(blueprint),
+  { title: "my-pkg", headingLevel: 2 },
+);
 // → "## my-pkg\n\nCapabilities: `commands`, `schema`\n\n### Commands\n\n- `greet hello`\n…"
 ```
 
@@ -461,7 +499,10 @@ const grouped = await pm.aggregate({ groupBy: "status", count: true });
 const stats = await pm.stats({ metadataCoverage: true });
 await pm.comments(created.item.id, { add: "Investigation context captured." });
 await pm.files(created.item.id, { add: ["src/index.ts"], note: "entrypoint" });
-await pm.docs(created.item.id, { add: ["docs/SDK.md"], note: "authoring reference" });
+await pm.docs(created.item.id, {
+  add: ["docs/SDK.md"],
+  note: "authoring reference",
+});
 const graph = await pm.deps(created.item.id, { format: "graph" });
 const types = await pm.schemaList();
 const profiles = await pm.profileList();
@@ -469,7 +510,10 @@ const validation = await pm.validate({ checkResolution: true });
 const health = await pm.health({ checkOnly: true, summary: true });
 const packages = await pm.packageList({ project: true });
 const doctor = await pm.packageDoctor({ project: true, isolated: true });
-const plannedUpgrade = await pm.upgrade(undefined, { dryRun: true, cliOnly: true });
+const plannedUpgrade = await pm.upgrade(undefined, {
+  dryRun: true,
+  cliOnly: true,
+});
 
 await runAction({
   action: "context",
@@ -493,11 +537,15 @@ integration, or agent runtime. Presentation stays outside the SDK primitive:
 callers choose their own rendering while the data shape remains shared with the
 CLI.
 
-The `next` result excludes the recommended item from the `ready` tail, reports
-foreign-owned work in `held_by_others`, and treats dangling dependency ids as
-unresolved blockers. The CLI `claim --next` composition uses the same public
-ranking result and atomic claim mutation, so custom SDK tools can apply their own
-selection policy without losing concurrency safety.
+The `next` result excludes the recommended item from the `ready` tail, assigns
+stable one-based ranks, reports foreign-owned work in `held_by_others`, and
+treats dangling dependency ids as unresolved blockers. Human-gated decisions
+remain visible in `decision_needed` but stay outside the agent-ready queue unless
+the caller explicitly opts in. `PmClient.claimNext()` and top-level `claimNext()`
+compose the same ranking result and atomic claim mutation, accept the next-work
+filters, and bound the race-loss candidate walk with `maxAttempts` (1 through
+100 inclusive), so custom SDK
+tools do not need to reproduce CLI concurrency policy.
 
 Lifecycle convenience methods and the matching top-level functions (`create`,
 `update`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
@@ -688,11 +736,19 @@ methods bind to the right sub-registry for you:
 ```ts
 import { createExtensionTestHarness } from "@unbrained/pm-cli/sdk/testing";
 
-const ext = await createExtensionTestHarness(extensionModule, { capabilities: ["commands", "schema"] });
+const ext = await createExtensionTestHarness(extensionModule, {
+  capabilities: ["commands", "schema"],
+});
 
-ext.assertCommandContract({ command: "incident triage", flags: ["--severity"] });
+ext.assertCommandContract({
+  command: "incident triage",
+  flags: ["--severity"],
+});
 ext.assertFlags({ targetCommand: "list", flags: ["--incident-filter"] });
-const { result } = await ext.runCommand({ command: "incident triage", options: { severity: "high" } });
+const { result } = await ext.runCommand({
+  command: "incident triage",
+  options: { severity: "high" },
+});
 const summary = ext.activationSummary();
 const reference = ext.renderMarkdown({ title: "incident package surfaces" });
 await ext.deactivate();
@@ -702,24 +758,24 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 
 ## Capability Requirements
 
-| Registration | Manifest capability |
-|--------------|---------------------|
-| `registerCommand` | `commands` |
-| inline command flags | `schema` |
-| `registerFlags` | `schema` |
-| `registerItemFields` | `schema` |
-| `registerItemTypes` | `schema` |
-| `registerMigration` | `schema` |
-| `registerProfile` | `schema` |
-| `registerImporter` | `importers` |
-| `registerExporter` | `importers` |
-| `registerParser` | `parser` |
-| `registerPreflight` | `preflight` |
-| `registerService` | `services` |
-| `registerRenderer` | `renderers` |
-| lifecycle hooks | `hooks` |
-| `registerSearchProvider` | `search` |
-| `registerVectorStoreAdapter` | `search` |
+| Registration                 | Manifest capability |
+| ---------------------------- | ------------------- |
+| `registerCommand`            | `commands`          |
+| inline command flags         | `schema`            |
+| `registerFlags`              | `schema`            |
+| `registerItemFields`         | `schema`            |
+| `registerItemTypes`          | `schema`            |
+| `registerMigration`          | `schema`            |
+| `registerProfile`            | `schema`            |
+| `registerImporter`           | `importers`         |
+| `registerExporter`           | `importers`         |
+| `registerParser`             | `parser`            |
+| `registerPreflight`          | `preflight`         |
+| `registerService`            | `services`          |
+| `registerRenderer`           | `renderers`         |
+| lifecycle hooks              | `hooks`             |
+| `registerSearchProvider`     | `search`            |
+| `registerVectorStoreAdapter` | `search`            |
 
 Some override surfaces are single-winner: command overrides, parser overrides, preflight overrides, and output renderers. Keep those handlers narrowly scoped and verify package combinations with:
 
@@ -754,7 +810,9 @@ export default defineExtension({
       description: "Return a deterministic hello payload.",
       intent: "verify SDK extension activation",
       examples: ["pm hello"],
-      failure_hints: ["Run pm package doctor --detail deep --trace on activation failures."],
+      failure_hints: [
+        "Run pm package doctor --detail deep --trace on activation failures.",
+      ],
       run: async () => ({ ok: true, message: "hello" }),
     });
   },
@@ -989,7 +1047,7 @@ the type level.
 pm packages are authored **and loaded** as TypeScript (ADR
 [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). A bare `const cmd = { ... }`
 satisfies the registration types only structurally and widens its literals;
-wrapping it in a builder checks the object against the contract *and* preserves
+wrapping it in a builder checks the object against the contract _and_ preserves
 the narrow literal types, while inferring the nested handler's `context`
 parameter from the builder signature — the same ergonomics `defineConfig` gives a
 Vite config. It also lets you colocate, export, reuse, and unit-test a definition
@@ -1046,7 +1104,11 @@ surfaces you use (ideally with `define*`-authored definitions) and leave the res
 out:
 
 ```ts
-import { composeExtension, defineCommand, deriveExtensionCapabilities } from "@unbrained/pm-cli/sdk";
+import {
+  composeExtension,
+  defineCommand,
+  deriveExtensionCapabilities,
+} from "@unbrained/pm-cli/sdk";
 import type { ExtensionBlueprint } from "@unbrained/pm-cli/sdk";
 
 const echo = defineCommand({
@@ -1059,7 +1121,9 @@ const echo = defineCommand({
 const blueprint: ExtensionBlueprint = {
   commands: [echo],
   parsers: { "command-kit echo": (context) => ({ options: context.options }) },
-  flags: { list: [{ long: "--kit-note", value_type: "string", value_name: "text" }] },
+  flags: {
+    list: [{ long: "--kit-note", value_type: "string", value_name: "text" }],
+  },
 };
 
 // The generated `activate` registers commands → overrides → flags → parsers →
@@ -1124,11 +1188,16 @@ export const commandsModule = defineExtensionBlueprint({
 
 ```ts
 // index.ts — the manifest entry; import sibling .ts modules by their real extension (loaded directly via native type stripping).
-import { composeExtension, mergeExtensionBlueprints } from "@unbrained/pm-cli/sdk";
+import {
+  composeExtension,
+  mergeExtensionBlueprints,
+} from "@unbrained/pm-cli/sdk";
 import { commandsModule } from "./commands.ts";
 import { searchModule } from "./search.ts";
 
-export default composeExtension(mergeExtensionBlueprints(commandsModule, searchModule));
+export default composeExtension(
+  mergeExtensionBlueprints(commandsModule, searchModule),
+);
 ```
 
 The merge is pure, deterministic, and never mutates an input. Each surface combines
@@ -1170,8 +1239,8 @@ const manifest = synthesizeExtensionManifest(blueprint, {
 manifest.capabilities; // ["commands", "parser", "schema"] — derived, not hand-written
 ```
 
-Where `defineExtensionManifest` only *types* a manifest you wrote by hand, this
-*generates* it. For the rare surface registered through the imperative `activate`
+Where `defineExtensionManifest` only _types_ a manifest you wrote by hand, this
+_generates_ it. For the rare surface registered through the imperative `activate`
 escape hatch (invisible to static derivation — e.g. a renderer wired in
 `activate`), pass `additionalCapabilities` and they are unioned in (legacy-alias
 resolved, unknown names dropped). Use the result as the on-disk `manifest.json`
@@ -1198,7 +1267,7 @@ const { module, manifest } = composeExtensionPackage(blueprint, {
   entry: "./index.ts",
   priority: 0,
 });
-export default module;          // the package entry's default export
+export default module; // the package entry's default export
 // write `manifest` verbatim as manifest.json — capabilities derived, never hand-synced
 ```
 
@@ -1221,7 +1290,10 @@ the runtime guardrails (the same discipline as `deriveExtensionCapabilities`
 inverting [`reconcileExtensionCapabilityUsage`](#capability-requirements)):
 
 ```ts
-import { describeExtensionBlueprint, lintExtensionBlueprint } from "@unbrained/pm-cli/sdk";
+import {
+  describeExtensionBlueprint,
+  lintExtensionBlueprint,
+} from "@unbrained/pm-cli/sdk";
 
 // describeExtensionBlueprint returns the same ExtensionActivationSummary shape as
 // the runtime describeExtensionActivation — but from the blueprint data alone, no
@@ -1234,8 +1306,10 @@ describeExtensionBlueprint(blueprint).command_handlers; // ["command-kit echo",
 // `error` (the loader throws extension_capability_missing); a declared-but-unused
 // capability, a duplicate command, a command/override conflict, and a present-but-
 // empty surface are `warning`s. Pass declaredCapabilities or set manifest.capabilities.
-const report = lintExtensionBlueprint(blueprint, { declaredCapabilities: ["commands", "parser", "schema"] });
-report.ok;       // false if any error-severity finding
+const report = lintExtensionBlueprint(blueprint, {
+  declaredCapabilities: ["commands", "parser", "schema"],
+});
+report.ok; // false if any error-severity finding
 report.findings; // [{ code, severity, message, capability?/command?/field? }, ...]
 ```
 
@@ -1292,7 +1366,7 @@ tests of extension registration shape; keep `pm package doctor` and runtime
 contracts in integration tests.
 
 For declarative (`composeExtension`) packages, `assertExtensionBlueprint(blueprint, options?)`
-is the `assert*` family member that preflights the blueprint *without* activating
+is the `assert*` family member that preflights the blueprint _without_ activating
 it — it runs `lintExtensionBlueprint` and throws if any finding is error-severity
 (today: a capability a surface exercises but the declared set omits, which would
 fail activation with `extension_capability_missing`). It returns the full
@@ -1309,7 +1383,7 @@ const report = assertExtensionBlueprint(blueprint);
 
 `assertExtensionManifestMatchesBlueprint(manifest, blueprint)` is the **strict**
 bookend to that lenient preflight: where `assertExtensionBlueprint` only fails on
-an *undeclared* capability and merely warns on an unused one, this assertion fails
+an _undeclared_ capability and merely warns on an unused one, this assertion fails
 on **both** — so a hand-maintained `manifest.json` stays exactly the least-privilege
 set the blueprint requires (assert what `synthesizeExtensionManifest` would
 otherwise generate). Only `capabilities` are reconciled, since that is the one
@@ -1325,7 +1399,7 @@ assertExtensionManifestMatchesBlueprint(manifest, blueprint);
 ```
 
 Where the blueprint guards `capabilities`, a manifest's `pm_min_version` /
-`pm_max_version` bounds guard *which pm CLI versions the package supports*.
+`pm_max_version` bounds guard _which pm CLI versions the package supports_.
 Tracker references: `pm-knma` introduced `checkExtensionManifestCompatibility`;
 `pm-hng2` introduced `assertExtensionManifestCompatible`.
 `checkExtensionManifestCompatibility(manifest, { pmVersion, pmMaxVersionExceededMode? })`
@@ -1343,7 +1417,9 @@ import { checkExtensionManifestCompatibility } from "@unbrained/pm-cli/sdk";
 import { assertExtensionManifestCompatible } from "@unbrained/pm-cli/sdk/testing";
 
 // Inspect every bound outcome against a target version…
-const report = checkExtensionManifestCompatibility(manifest, { pmVersion: "2026.6.23" });
+const report = checkExtensionManifestCompatibility(manifest, {
+  pmVersion: "2026.6.23",
+});
 //   report.compatible === false, report.findings[0].code === "pm_min_version_unmet", …
 
 // …or fail the package's own suite when a bound would block the load.
@@ -1375,14 +1451,24 @@ import { assertExtensionPreflight } from "@unbrained/pm-cli/sdk/testing";
 
 // Inspect every author-time stage in one report…
 const report = preflightExtension(blueprint, {
-  identity: { name: "command-kit", version: "1.0.0", entry: "./index.ts", priority: 0 },
+  identity: {
+    name: "command-kit",
+    version: "1.0.0",
+    entry: "./index.ts",
+    priority: 0,
+  },
   target: { pmVersion: "2026.6.23" },
 });
 //   report.manifest.capabilities (derived), report.compatibility.compatible, report.findings[]
 
 // …or guard the whole package in one CI line.
 assertExtensionPreflight(blueprint, {
-  identity: { name: "command-kit", version: "1.0.0", entry: "./index.ts", priority: 0 },
+  identity: {
+    name: "command-kit",
+    version: "1.0.0",
+    entry: "./index.ts",
+    priority: 0,
+  },
   target: { pmVersion: "2026.6.23" },
 });
 ```
@@ -1407,13 +1493,18 @@ the `"<name> import"` / `"<name> export"` command path. Pass the whole `activati
 and the registration name:
 
 ```ts
-import { runRegisteredImporterForTest, runRegisteredExporterForTest } from "@unbrained/pm-cli/sdk/testing";
+import {
+  runRegisteredImporterForTest,
+  runRegisteredExporterForTest,
+} from "@unbrained/pm-cli/sdk/testing";
 
 const imported = await runRegisteredImporterForTest(activation, {
   importer: "csv",
   options: { rows: 3 },
 });
-const exported = await runRegisteredExporterForTest(activation, { exporter: "csv" });
+const exported = await runRegisteredExporterForTest(activation, {
+  exporter: "csv",
+});
 
 // Both return a CommandHandlerResult: imported.result is the importer's return value.
 ```
@@ -1454,10 +1545,13 @@ const parsed = await runRegisteredParserOverrideForTest(activation.parsers, {
 });
 // parsed.overridden === true; parsed.context holds the rewritten args/options.
 
-const rendered = await runRegisteredRendererOverrideForTest(activation.renderers, {
-  format: "toon",
-  result: { id: "pm-1a2b" },
-});
+const rendered = await runRegisteredRendererOverrideForTest(
+  activation.renderers,
+  {
+    format: "toon",
+    result: { id: "pm-1a2b" },
+  },
+);
 // rendered.rendered is the custom string the override produced.
 ```
 
@@ -1490,8 +1584,12 @@ assertRegisteredExporter(activation.registrations, {
   exporter: "jsonl",
   extensionName: "my-ext",
 });
-assertRegisteredSearchProvider(activation.registrations, { provider: "semantic-local" });
-assertRegisteredVectorStoreAdapter(activation.registrations, { adapter: "pinecone" });
+assertRegisteredSearchProvider(activation.registrations, {
+  provider: "semantic-local",
+});
+assertRegisteredVectorStoreAdapter(activation.registrations, {
+  adapter: "pinecone",
+});
 ```
 
 Use `assertRegisteredVectorStoreAdapter` for packages that call
@@ -1549,7 +1647,10 @@ import {
 } from "@unbrained/pm-cli/sdk/testing";
 
 assertRegisteredCommandOverride(activation.commands, { command: "list" });
-assertRegisteredParserOverride(activation.parsers, { command: "list", extensionName: "my-ext" });
+assertRegisteredParserOverride(activation.parsers, {
+  command: "list",
+  extensionName: "my-ext",
+});
 assertRegisteredPreflightOverride(activation.preflight); // preflight overrides are global (no command)
 assertRegisteredRendererOverride(activation.renderers, { format: "toon" });
 ```
@@ -1605,9 +1706,17 @@ export const kanbanProfile = defineProjectProfile({
   summary: "WIP-limited flow with a verifying stage.",
   types: [{ name: "Card", folder: "cards" }],
   statuses: [{ id: "doing", roles: ["active"] }],
-  fields: [{ key: "wip_limit", type: "number", commands: ["create", "update"] }],
+  fields: [
+    { key: "wip_limit", type: "number", commands: ["create", "update"] },
+  ],
   workflows: [{ type: "Card", allowed_transitions: [["open", "doing"]] }],
-  config: [{ key: "search_provider", value: "bm25", summary: "Offline lexical search." }],
+  config: [
+    {
+      key: "search_provider",
+      value: "bm25",
+      summary: "Offline lexical search.",
+    },
+  ],
   templates: [{ name: "card", options: { type: "Card" } }],
   packages: [{ spec: "templates", reason: "Reusable card shapes." }],
 });
@@ -1629,7 +1738,9 @@ surface to `schema`. Prove a profile registered with `assertRegisteredProfile`:
 ```ts
 import { assertRegisteredProfile } from "@unbrained/pm-cli/sdk/testing";
 
-const { profile } = assertRegisteredProfile(activation.registrations, { profile: "kanban" });
+const { profile } = assertRegisteredProfile(activation.registrations, {
+  profile: "kanban",
+});
 // profile is the normalized ProjectProfileDefinition
 ```
 
@@ -1651,11 +1762,21 @@ import {
 
 // Invoke a registered provider's semantic query (or embed / embedBatch /
 // queryExpansion / rerank); the result type follows `operation`.
-const hits = await runRegisteredSearchProviderForTest(activation.registrations, {
-  provider: "semantic-local",
-  operation: "query",
-  context: { query: "calendar", mode: "semantic", tokens: ["calendar"], options: {}, settings, documents },
-});
+const hits = await runRegisteredSearchProviderForTest(
+  activation.registrations,
+  {
+    provider: "semantic-local",
+    operation: "query",
+    context: {
+      query: "calendar",
+      mode: "semantic",
+      tokens: ["calendar"],
+      options: {},
+      settings,
+      documents,
+    },
+  },
+);
 
 // Invoke a registered adapter's upsert / query / delete.
 await runRegisteredVectorStoreAdapterForTest(activation.registrations, {
@@ -1711,7 +1832,11 @@ export default defineExtension({
         aliases: ["incident"],
         required_create_fields: ["title", "description", "severity"],
         options: [
-          { key: "severity", values: ["critical", "major", "minor"], required: true },
+          {
+            key: "severity",
+            values: ["critical", "major", "minor"],
+            required: true,
+          },
           { key: "service", values: ["api", "web", "worker"] },
         ],
       },
@@ -1810,8 +1935,16 @@ export default defineExtension({
       name: "example-search",
       async query(context) {
         return context.documents
-          .filter((doc) => doc.metadata.title?.toLowerCase().includes(context.query.toLowerCase()))
-          .map((doc) => ({ id: doc.metadata.id, score: 0.5, matched_fields: ["title"] }));
+          .filter((doc) =>
+            doc.metadata.title
+              ?.toLowerCase()
+              .includes(context.query.toLowerCase()),
+          )
+          .map((doc) => ({
+            id: doc.metadata.id,
+            score: 0.5,
+            matched_fields: ["title"],
+          }));
       },
     });
   },

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.1"
+    "version": "2026.7.12"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "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",
+      "version": "2026.7.12",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.11",
+  "version": "2026.7.12",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -91,8 +91,9 @@
     "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",
+    "version:check": "node scripts/release-version.mjs check && node scripts/sync-versions.mjs check",
     "version:next": "node scripts/release-version.mjs next",
+    "version:sync": "node scripts/sync-versions.mjs apply",
     "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
     "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
     "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",

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

@@ -1,3 +1,4 @@
+/** @module packages/pm-beads/extensions/beads/runtime-loader */
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -11,6 +12,7 @@ const CURRENT_EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
 const EXTENSION_NAME = "beads";
 const PACKAGE_NAME = "pm-beads";
 const DIAGNOSTIC_NAME = "beads";
+/** Runtime module exports loaded from the installed package or co-located extension. */
 export type PackageRuntimeModule = Record<string, unknown>;
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -94,6 +96,7 @@ async function tryRuntime(modulePath: string, attempted: string[]): Promise<Pack
   }
 }
 
+/** Resolve and load the first usable packaged runtime module. */
 export async function loadPackageRuntimeModule(): Promise<PackageRuntimeModule> {
   const attempted: string[] = [];
   for (const modulePath of [...resolvePackageRootCandidates().flatMap(runtimePaths), path.join(CURRENT_EXTENSION_ROOT, "runtime.ts")]) {