@unbrained/pm-cli 2026.8.26 → 2026.8.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.26",
+  "version": "2026.8.27",
   "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"
   ],
@@ -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",