@unbrained/pm-cli 2026.10.5 → 2026.10.6

package/docs/SDK_CONFIGURATION_SAFETY.md

@@ -0,0 +1,123 @@
+# SDK Configuration and Diagnostic Safety
+
+Trackers: [pm-gh1394](../.agents/pm/issues/pm-gh1394.toon), [pm-gh1393](../.agents/pm/issues/pm-gh1393.toon), [pm-gh1392](../.agents/pm/issues/pm-gh1392.toon), [pm-gh1398](../.agents/pm/issues/pm-gh1398.toon).
+
+Package authors use the host-injected `context.sdk` services to change project
+configuration. The SDK owns settings normalization, locking, immutable audit
+history, retry identity, and dry-run behavior. See [SDK](SDK.md) and
+[Packages and Extensions](EXTENSIONS.md) for the broader authoring contract.
+
+## Explicit Settings Ownership
+
+`mutateWorkspaceSettings` preserves unknown source fields by default. A package
+that replaces a complete settings object can explicitly declare the objects it
+owns with `replaceSubtrees`:
+
+```ts
+await context.sdk!.mutateWorkspaceSettings({
+  operationId: "apply-governance-policy",
+  replaceSubtrees: ["governance"],
+  includePreview: true,
+  dryRun: context.options.dryRun === true,
+  mutate: (current) => ({
+    ...current,
+    governance: { ...current.governance, preset: "minimal" },
+  }),
+});
+```
+
+The selected object is replaced by its normalized serialized value, removing
+unknown raw keys omitted from the callback's result. Unselected source fields,
+including future root fields and sibling objects, are preserved. Dot-delimited
+paths such as `search.rerank` select nested objects. Missing ancestors are
+materialized with their canonical settings so the complete persisted document
+remains valid. Scalar, array, unknown, and prototype paths are rejected before
+writing. Declare ownership only for configuration the package is authorized to
+replace. An empty ownership list retains the default preservation behavior.
+
+Replacement runs inside the same settings lock and history transaction as the
+callback. Dry runs write no settings or workspace history; retries with the same
+operation identity skip the callback after a successful commit. Fresh semantic
+no-ops preserve the existing bytes and produce no history event.
+
+The optional `preview` describes normalized inline settings resolved from the
+exact proposed bytes. Preset-derived values can be omitted from serialized JSON
+and reconstructed in the preview. File-backed schema overlays and unknown raw
+keys are outside this normalized preview. Inspect the persisted document when
+raw-source information is needed.
+
+## Read-only Package Freshness
+
+`pm package explore`, `doctor`, and `manage` preserve managed installation state.
+`manage` checks GitHub revisions and npm registry identities transiently; it
+does not rewrite `.managed-extensions.json`, reorder its contribution inventory,
+or advance its modification time. Install, update, and explicit adoption own
+managed-state persistence. `--fix-managed-state` remains an explicit adoption
+mutation.
+
+```bash
+pm package manage --project --json
+pm package manage --project --offline --json
+```
+
+For npm sources the SDK compares the recorded package version with the configured
+registry's `latest` dist-tag, honoring npm registry configuration. A different
+dist-tag version reports `update_available: true`; this is a channel comparison,
+including an intentional registry rollback. `last_update_remote_version` identifies
+the observed registry version. Missing provenance, invalid metadata, and failed
+lookups report unknown availability and incomplete health. Lookups are bounded
+to ten seconds and 64 KiB. npm execution failures use a stable public diagnostic
+code to avoid exposing registry credentials through command stderr. Invalid
+installed versions, registry versions, and JSON metadata also use stable reasons
+that do not reflect their raw contents.
+
+`--offline` performs no remote freshness lookup and reports `not_checked`,
+`offline_requested`, and unknown availability for supported remote sources.
+Runtime activation diagnostics still run. A bare installed npm extension name
+or recorded package name reuses its managed registry identity on reinstall;
+explicit local paths and bundled aliases retain their existing precedence.
+For a confirmed missing bare input, npm records match by exact manifest name,
+then stored directory, then recorded package identity. A weaker identity match
+cannot replace a stronger match because its record appears earlier.
+The selected stored package must parse as exactly one registry package name.
+URLs, local files, aliases, versioned specs, options, and shell-bearing values
+cannot become installation authority through managed metadata; invalid identity
+retains local-source recovery. Explicit `npm:` sources still accept their existing
+caller-selected package specs. Managed state is local installation provenance
+written by lifecycle operations, not permission for arbitrary source execution;
+protect project and global extension roots with the invoking account's filesystem
+permissions.
+
+## Isolated Schema History
+
+Linked tests using `pm_context_mode=schema` inherit project and global settings
+and extensions without inheriting source items. Settings are seeded through the
+workspace history writer against each sandbox's own initialized state. Nested
+`pm validate --check-history-drift --strict-exit` therefore validates that
+sandbox's configuration successfully. Out-of-band sandbox edits still fail
+history validation. Tracker context continues to retain the source audit history
+and its genuine drift. Source settings and history are never changed by seeding.
+
+## Help Discovery Before Mutation
+
+Bare `--help` and `-h` following declared options are discovery requests:
+
+```bash
+pm test pm-example --add --help
+pm files pm-example --add -h
+pm update pm-example -b -h
+pm create --file --help
+```
+
+These invocations print help and leave item and history bytes unchanged. To
+persist a literal flag-looking value, attach it explicitly: `--add=--help`.
+JSON help follows the same discovery policy. Bootstrap normalization preserves
+the argv terminator and attached values. The immediately preceding declared
+option is neutralized before parsing, regardless of whether its contract has
+value metadata. Short options, aliases, and booleans follow the same policy;
+no value parser runs for the neutralized option. The original help token stays
+reachable even when another adjacent option consumes the replacement token.
+Global boolean flags retain their presentation semantics, so `--json --help`
+still renders JSON help.
+Explicit bare assignments preserve a single value boundary during expansion,
+so values such as `body=--help` retain their literal meaning.

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -7,9 +7,9 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `init` | workspace | 30 | 30 |
 | `item` | intake | 20 | 20 |
 | `config` | workspace | 36 | 36 |
-| `extension` | extensions | 54 | 54 |
-| `package` | extensions | 55 | 55 |
-| `packages` | extensions | 55 | 55 |
+| `extension` | extensions | 55 | 55 |
+| `package` | extensions | 56 | 56 |
+| `packages` | extensions | 56 | 56 |
 | `install` | extensions | 27 | 27 |
 | `upgrade` | extensions | 29 | 29 |
 | `create` | intake | 100 | 100 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,12 +4,12 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 393
+- Catalog error codes: 394
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 374
-- Coverage fraction: 0.048346
+- Uncovered error codes: 375
+- Coverage fraction: 0.048223
 - Closed-domain probes: 19
 - Grammar probes: 117
 
@@ -31,6 +31,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `append_empty_body` | `append_empty_body` | uncovered | none | 0 |
 | `assurance_registry_invalid` | `assurance_registry_invalid` | uncovered | none | 0 |
 | `bare_comma_entry_ambiguous` | `bare_comma_entry_ambiguous` | uncovered | none | 0 |
+| `blocker_identity_read_failed` | `blocker_identity_read_failed` | uncovered | none | 0 |
 | `body_file_conflicts_with_body` | `body_file_conflicts_with_body` | uncovered | none | 0 |
 | `body_file_missing_path` | `body_file_missing_path` | uncovered | none | 0 |
 | `body_file_unreadable` | `body_file_unreadable` | uncovered | none | 0 |

package/marketplace.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -235,7 +235,7 @@
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
     "eslint": "^10.11.0",
-    "eslint-plugin-sonarjs": "^4.2.1",
+    "eslint-plugin-sonarjs": "^4.2.2",
     "eslint-plugin-unicorn": "76.0.0",
     "fast-check": "^4.10.2",
     "github-slugger": "2.0.0",
@@ -246,7 +246,7 @@
     "parse5": "8.0.1",
     "tsx": "^4.23.15",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.70.1",
+    "typescript-eslint": "^8.71.0",
     "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

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

@@ -3,7 +3,7 @@
   "name": "pm-claude",
   "displayName": "pm CLI",
   "description": "Native pm CLI integration for Claude Code — 32 MCP tools, 14 skills with slash invocations, 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": "2026.10.5",
+  "version": "2026.10.6",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/package.json

@@ -2,8 +2,8 @@
   "name": "pm-claude-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.10.5"
+    "@unbrained/pm-cli": "2026.10.6"
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",

package/plugins/pm-codex/package.json

@@ -2,8 +2,8 @@
   "name": "pm-codex-runtime",
   "private": true,
   "type": "module",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "dependencies": {
-    "@unbrained/pm-cli": "2026.10.5"
+    "@unbrained/pm-cli": "2026.10.6"
   }
 }

package/plugins/pm-codex/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pm-codex",
-  "version": "2026.10.5",
+  "version": "2026.10.6",
   "description": "Repository-native project context workflows and a version-pinned pm MCP server for Codex.",
   "author": {
     "name": "unbrained",