@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/docs/agent-task-transcripts.json

@@ -0,0 +1,211 @@
+{
+  "version": 2,
+  "tasks": [
+    {
+      "id": "context-bootstrap",
+      "description": "Orient in a scaled workspace and inspect the canonical focus item.",
+      "steps": [
+        {
+          "id": "triage",
+          "args": ["list", "--for", "triage", "--limit", "2"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["items"]
+        },
+        {
+          "id": "orient",
+          "args": ["context", "--for", "orient", "--limit", "5"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "diagnostic",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["summary.active_items", "hierarchy", "activity"]
+        },
+        {
+          "id": "inspect",
+          "args": ["get", "$ANCHOR_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id"]
+        }
+      ]
+    },
+    {
+      "id": "closed-domain-recovery",
+      "description": "Reject an invalid context intent and execute the advertised shell-free retry.",
+      "steps": [
+        {
+          "id": "refuse-intent",
+          "args": ["get", "$ANCHOR_ID", "--for", "invalid-agent-intent"],
+          "expected_exit_code": 2,
+          "expected_output_kind": "refusal",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["code", "refusal", "recovery"],
+          "expected_error_code": "unknown_context_intent",
+          "expected_refusal_surface": "--for"
+        },
+        {
+          "id": "retry-intent",
+          "args": ["get", "$ANCHOR_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id"],
+          "recovery_for": "refuse-intent"
+        }
+      ]
+    },
+    {
+      "id": "unknown-option-recovery",
+      "description": "Identify an unsupported option after valid flags and continue with the corrected command.",
+      "steps": [
+        {
+          "id": "refuse-option",
+          "args": [
+            "search",
+            "agent task",
+            "--status",
+            "open",
+            "--limit",
+            "5",
+            "--include-body"
+          ],
+          "expected_exit_code": 2,
+          "expected_output_kind": "refusal",
+          "expected_accounting_mode": "independent_transport",
+          "required_fields": ["code", "refusal", "recovery"],
+          "expected_error_code": "unknown_option",
+          "expected_refusal_surface": "--include-body"
+        },
+        {
+          "id": "retry-option",
+          "args": ["search", "agent task", "--status", "open", "--limit", "5"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["items"],
+          "recovery_for": "refuse-option"
+        }
+      ]
+    },
+    {
+      "id": "lifecycle-mutation",
+      "description": "Create, inspect, close, and confirm a project item through public CLI receipts.",
+      "steps": [
+        {
+          "id": "create",
+          "args": [
+            "create",
+            "--id",
+            "$LIFECYCLE_ID",
+            "--title",
+            "Transcript lifecycle item",
+            "--description",
+            "Golden multi-step lifecycle task",
+            "--type",
+            "Task",
+            "--status",
+            "open",
+            "--create-mode",
+            "progressive"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "changed_field_count"]
+        },
+        {
+          "id": "inspect-open",
+          "args": ["get", "$LIFECYCLE_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id", "item.status"],
+          "expected_field_values": { "item.status": "open" }
+        },
+        {
+          "id": "close",
+          "args": ["close", "$LIFECYCLE_ID", "Golden task completed"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "status", "close_reason"]
+        },
+        {
+          "id": "inspect-closed",
+          "args": ["get", "$LIFECYCLE_ID", "--for", "inspect"],
+          "expected_exit_code": 0,
+          "expected_output_kind": "entity",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["item.id", "item.status"],
+          "expected_field_values": { "item.status": "closed" }
+        }
+      ]
+    },
+    {
+      "id": "bulk-effect-outcomes",
+      "description": "Preserve successful partial-effect and no-effect outcomes across a bulk lifecycle task.",
+      "steps": [
+        {
+          "id": "create-bulk-target",
+          "args": [
+            "create",
+            "--id",
+            "$BULK_ID",
+            "--title",
+            "Transcript bulk effect target",
+            "--description",
+            "Golden bulk outcome transcript target",
+            "--type",
+            "Task",
+            "--status",
+            "open",
+            "--create-mode",
+            "progressive"
+          ],
+          "expected_exit_code": 0,
+          "expected_output_kind": "mutation_receipt",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["id", "status", "changed_field_count"]
+        },
+        {
+          "id": "partial-effect",
+          "args": [
+            "close-many",
+            "--ids",
+            "$BULK_ID,pm-transcript-missing",
+            "--reason",
+            "Golden partial-effect transcript",
+            "--validate-close",
+            "off",
+            "--no-checkpoint"
+          ],
+          "expected_exit_code": 7,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["rows", "outcome", "exit_code"],
+          "expected_field_values": { "outcome": "partial_effect" }
+        },
+        {
+          "id": "no-effect",
+          "args": [
+            "close-many",
+            "--ids",
+            "$BULK_ID",
+            "--reason",
+            "Golden no-effect transcript",
+            "--validate-close",
+            "off",
+            "--no-checkpoint"
+          ],
+          "expected_exit_code": 6,
+          "expected_output_kind": "collection",
+          "expected_accounting_mode": "self_reported",
+          "required_fields": ["rows", "outcome", "exit_code"],
+          "expected_field_values": { "outcome": "no_effect" }
+        }
+      ]
+    }
+  ]
+}

package/docs/generated/AGENT_CAPABILITY_ROUTING.md

@@ -14,4 +14,4 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
 | graph | `graph`, `deps`, `plan` |
 | quality | `test`, `test-all`, `validate`, `assurance`, `contracts` |
 | automation | `meet`, `event`, `remind` |
-| extensions | `extension`, `package`, `packages`, `install`, `upgrade` |
+| extensions | `package` |

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -48,9 +48,9 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `close-many` | lifecycle | 72 | 72 |
 | `delete` | lifecycle | 24 | 24 |
 | `append` | evidence | 24 | 24 |
-| `comments` | evidence | 30 | 30 |
-| `notes` | evidence | 34 | 34 |
-| `learnings` | evidence | 26 | 26 |
+| `comments` | evidence | 31 | 31 |
+| `notes` | evidence | 35 | 35 |
+| `learnings` | evidence | 27 | 27 |
 | `files` | evidence | 39 | 39 |
 | `docs` | evidence | 30 | 30 |
 | `deps` | graph | 32 | 32 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ 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: 343
-- Executable error codes: 18
+- Catalog error codes: 347
+- 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: 325
-- Coverage fraction: 0.052478
-- Closed-domain probes: 18
-- Grammar probes: 95
+- Uncovered error codes: 328
+- Coverage fraction: 0.054755
+- Closed-domain probes: 19
+- Grammar probes: 94
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -25,6 +25,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `ambiguous_option_combination` | `ambiguous_option_combination` | uncovered | none | 0 |
 | `annotation_alias_conflict` | `annotation_alias_conflict` | uncovered | none | 0 |
 | `annotation_flag_like_value` | `annotation_flag_like_value` | uncovered | none | 0 |
+| `annotation_if_absent_without_append` | `annotation_if_absent_without_append` | uncovered | none | 0 |
 | `annotation_message_without_text` | `annotation_message_without_text` | uncovered | none | 0 |
 | `annotation_transposed_subcommand` | `annotation_transposed_subcommand` | uncovered | none | 0 |
 | `append_empty_body` | `append_empty_body` | uncovered | none | 0 |
@@ -198,7 +199,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_observed_signature` | `missing_observed_signature` | uncovered | none | 0 |
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 58 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
@@ -213,11 +214,14 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `no_update_fields` | `no_update_fields` | uncovered | none | 0 |
 | `no_version_bounds_declared` | `no_version_bounds_declared` | executable | owned_state | 1 |
 | `non_refusal_exit` | `non_refusal_exit` | uncovered | none | 0 |
+| `npm_package_archive_missing` | `npm_package_archive_missing` | uncovered | none | 0 |
+| `npm_package_archive_unsafe` | `npm_package_archive_unsafe` | uncovered | none | 0 |
 | `npm_package_not_found` | `npm_package_not_found` | uncovered | none | 0 |
 | `ownership_conflict` | `ownership_conflict` | uncovered | none | 0 |
 | `ownership_dependency_bypass_restricted_options` | `ownership_dependency_bypass_restricted_options` | uncovered | none | 0 |
 | `ownership_metadata_bypass_restricted_options` | `ownership_metadata_bypass_restricted_options` | uncovered | none | 0 |
 | `package_spec_empty` | `package_spec_empty` | uncovered | none | 0 |
+| `package_upgrade_modes_mutually_exclusive` | `package_upgrade_modes_mutually_exclusive` | executable | closed_domain | 1 |
 | `positional_shape_budget_exceeded` | `positional_shape_budget_exceeded` | uncovered | none | 0 |
 | `positional_signature_mismatch` | `positional_signature_mismatch` | uncovered | none | 0 |
 | `profile_name_empty` | `profile_name_empty` | uncovered | none | 0 |

package/docs/performance/cli-transport-overhead.md

@@ -1,12 +1,20 @@
 # CLI transport overhead
 
-Tracked by [pm-yse5dt](../../.agents/pm/tasks/pm-yse5dt.toon).
+Tracked by [pm-yse5dt](../../.agents/pm/tasks/pm-yse5dt.toon), with RSS
+admission reliability owned by
+[pm-pz49xc](../../.agents/pm/issues/pm-pz49xc.toon).
 
 Each result starts from a fresh isolated workspace containing exactly one item.
 The command runs in a fresh Node v26.5.0 process on
 linux/x64; setup and fixture generation are
 outside the timed interval. Short local gates use the best observed latency,
-while the report retains p50 and p95 evidence.
+while the report retains p50 and p95 evidence. RSS admission uses the measured
+median so one page-level outlier cannot false-fail the gate; the maximum remains
+in the report as diagnostic evidence. Every post-warmup RSS sample must be a
+finite measurement; an unavailable sample makes the admission median unavailable
+and fails closed when a budget exists. Admission adds a fixed 512 KiB noise margin
+without changing the committed budget; a majority persistent increase beyond
+that bounded margin still fails.
 
 | Command   |   best |    p50 |    p95 |
 | --------- | -----: | -----: | -----: |

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": "2026.8.26"
+    "version": "2026.8.28"
   },
   "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": "2026.8.26",
+      "version": "2026.8.28",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.26",
+  "version": "2026.8.28",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -104,6 +104,7 @@
     "scripts/finalize-build.mjs",
     "scripts/install.sh",
     "scripts/install.ps1",
+    ".agents/skills/**",
     "scripts/prepare-build-cache.mjs",
     "marketplace.json"
   ],
@@ -121,7 +122,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
+    "quality:static": "pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
     "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
     "quality:recovery-closure": "pnpm build && node scripts/release/refusal-closure-gate.mjs",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
@@ -167,7 +168,7 @@
     "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:install": "node dist/cli.js package 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 --exclude-tag changelog-exclude --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 --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
@@ -212,17 +213,19 @@
     "fast-glob": "^3.3.3",
     "fast-json-patch": "^3.1.1",
     "npm-package-arg": "^13.0.2",
-    "tar": "7.5.22"
+    "tar": "7.5.22",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.2",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
-    "eslint": "^10.9.0",
+    "eslint": "^10.9.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
@@ -231,7 +234,6 @@
     "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.68.0",
-    "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/README.md

@@ -1,10 +1,16 @@
 # pm Beads Package
 
-First-party pm package for importing Beads JSONL records.
+First-party pm package for lossless Beads migration through public pm SDK
+contracts. The importer preserves issue identity, comments, structured events,
+relationships, labels, and terminal closure evidence before reporting a
+complete count-parity receipt.
 
-```bash
-pm install ./packages/pm-beads --project
-pm beads import --file .beads/issues.jsonl
-```
+## Migration
 
-The package exposes the `beads import` extension command through the `pm.extensions` package manifest. Runtime sources are authored in TypeScript and shipped with JavaScript entry artifacts for Node extension loading.
+Use a current portable backup for lossless relational migration. The focused
+[migration guide](docs/MIGRATION.md) covers installation, source validation,
+ID preservation, legacy exports, parity receipts, and post-import checks.
+
+The package exposes the `beads import` extension command through the
+`pm.extensions` package manifest. Runtime sources are TypeScript and use only
+the published `@unbrained/pm-cli/sdk` surface.

package/packages/pm-beads/docs/MIGRATION.md

@@ -0,0 +1,53 @@
+# Beads Migration
+
+Tracker: [pm-tpwde6](../../../.agents/pm/issues/pm-tpwde6.toon)
+
+## Lossless portable-backup migration
+
+Install the package, create a current Beads portable backup, and import the
+backup directory without modifying the source project:
+
+```bash
+pm package install ./packages/pm-beads --project
+bd backup --force
+pm beads import --backup-dir .beads/backup --preserve-source-ids
+```
+
+Current Beads backups contain relational `issues.jsonl`, `comments.jsonl`,
+`events.jsonl`, `dependencies.jsonl`, and `labels.jsonl` files plus
+`backup_state.json`. The importer validates those files, their foreign keys,
+the backup counts, source-ID collisions, and every issue before the first pm
+write. Structural source failures therefore cannot leave a partially imported
+tracker; each later item commit also retains pm's normal lock and rollback
+guarantees.
+
+Successful output includes `complete: true`, source and imported counts for
+each relation, and an exact `id_mapping`. Source IDs are preserved only when
+they are safe path identifiers and do not collide case-insensitively with one
+another or with the target tracker. Comments remain comments, Beads events are
+stored as structured JSON notes, dependencies retain their source identity,
+label text is normalized to canonical lowercase pm tags, and a
+terminal Beads close reason becomes the pm resolution when no explicit source
+resolution exists.
+
+Verify representative records and the final tracker after import:
+
+```bash
+pm get Tokenwerk-A1
+pm comments Tokenwerk-A1
+pm validate --check-resolution --check-history-drift
+```
+
+## Legacy single-file import
+
+Older JSON/JSONL exports with embedded `comments`, `events`, `dependencies`,
+and `labels` remain supported:
+
+```bash
+pm beads import --file .beads/issues.jsonl
+```
+
+A current plain `bd export` that advertises `comment_count` but omits comment
+bodies is intentionally rejected before any write. Run `bd backup --force` and
+use `--backup-dir` instead so the migration cannot silently lose discussion or
+event history.

package/packages/pm-beads/extensions/beads/index.ts

@@ -37,6 +37,7 @@ function toBeadsImportOptions(
 ): BeadsImportOptions {
   return {
     file: asOptionalString(options.file),
+    backupDir: asOptionalString(options.backupDir),
     author: global.author,
     message: asOptionalString(options.message),
     preserveSourceIds: asBoolean(options.preserveSourceIds),
@@ -69,6 +70,13 @@ export function activate(api: ExtensionApi): void {
           value_type: "string",
           description: "Path to the Beads JSONL source file.",
         },
+        {
+          long: "--backup-dir",
+          value_name: "path",
+          value_type: "string",
+          description:
+            "Path to a complete bd portable-backup directory with issue, event, comment, dependency, label, and count files.",
+        },
         {
           long: "--message",
           value_name: "text",