@unbrained/pm-cli 2026.8.4 → 2026.8.6

package/docs/SELF_DESCRIBING_CONTEXT_CONTRACTS.md

@@ -75,8 +75,21 @@ The default summary stays bounded. Larger intent and error catalogs are emitted
 - the stable snake-case code;
 - meaning and stability;
 - CLI exit code;
+- semantic exit class (`generic_failure`, `usage`, `not_found`, `conflict`, or `dependency_failed`);
 - recovery guidance;
 - source modules that emit the code.
+- inferred CLI command roots (`*` for cross-cutting runtime failures).
+
+Existing catalog entries are recorded in `scripts/error-code-stability.json`.
+The generator refuses to remove one of those stable codes unless the reviewed
+compatibility ledger is changed explicitly. Newly discovered codes are emitted
+as provisional until deliberately promoted, so adding a runtime declaration
+does not accidentally promise permanent compatibility.
+
+`PM_ERROR_CODE_EXIT_CLASS_CONTRACTS` is the portable shell taxonomy: exit 1 is
+generic failure, 2 is usage, 3 is not-found, 4 is conflict, and 5 is dependency
+failure. Catalog validation rejects a code whose declared semantic class and
+transport exit disagree.
 
 Run the drift gate after adding or removing a structured error:
 

package/docs/TESTING.md

@@ -248,6 +248,31 @@ step also fails until stale policy is reconciled. Public source claims are
 mapped to exact evidence strings and an enforced registry entry so
 documentation cannot silently advertise advisory behavior.
 
+## Tracker Context-Quality Ratchets
+
+Tracked by [pm-ips23h](../.agents/pm/issues/pm-ips23h.toon) and
+[pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon).
+
+`scripts/release/tracker-measurements.json` turns measured tracker populations
+into reviewed, shrinking-only ceilings. Each declaration names its canonical
+pm owner and a selector over stored dependency kinds, validator warnings,
+graph-profile fields, or health-check severity. Open owners enforce their
+ceiling; terminal owners retire it. Validator warnings and health checks are
+exhaustive, so a newly observed class fails until it has a canonical owner and
+reviewed declaration.
+
+Run the same gate used by hosted CI:
+
+```bash
+pnpm quality:tracker-measurements
+node scripts/release/tracker-measurement-gate.mjs --negative-control
+```
+
+`--update` can only lower a ceiling. It refuses to write while any population
+has regressed or remains undeclared, so updating the baseline cannot absorb a
+failure. Dependency-kind regressions include the post-measurement item, target,
+author, timestamp, and mutation-source rows in the JSON receipt.
+
 ## Agent Output Token Budgets
 
 Run the required PR gate locally:

package/docs/examples/sdk-contract-consumer/README.md

@@ -6,6 +6,7 @@ This example shows how to consume `pm` contracts programmatically in a script an
 
 - `package.json` -> installs `@unbrained/pm-cli` and script aliases
 - `inspect-contracts.mjs` -> loads contracts + SDK helpers and prints required/optional parameter metadata
+- `parse-receipt.mjs` -> executes a real create and parses its flat mutation receipt with the SDK
 
 ## Run
 
@@ -20,6 +21,7 @@ npm install "$PM_CLI_REPO_ROOT"
 # npm install @unbrained/pm-cli@latest
 
 node inspect-contracts.mjs create
+npm run parse:receipt
 ```
 
 Expected output shape:
@@ -27,7 +29,14 @@ Expected output shape:
 ```json
 {
   "action": "create",
-  "required_parameters": ["title", "description", "type", "status", "priority", "message"],
+  "required_parameters": [
+    "title",
+    "description",
+    "type",
+    "status",
+    "priority",
+    "message"
+  ],
   "optional_parameters": ["template", "createMode", "schedulePreset"],
   "any_of_required_groups": [],
   "runtime_available": true,
@@ -55,3 +64,4 @@ node inspect-contracts.mjs extension-reload
 - Uses `PM_TOOL_ACTION_PARAMETER_CONTRACTS` for deterministic required/optional metadata.
 - Uses runtime `pm contracts --json` so extension-provided actions and command availability are reflected.
 - Includes policy-state and compatibility metadata so CI/app callers can gate behavior during v1 -> v2 migrations.
+- Uses `parseMutationReceipt()` at the process boundary instead of guessing that mutation output has the read-only `{ item: ... }` wrapper.

package/docs/examples/sdk-contract-consumer/package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "inspect:create": "node inspect-contracts.mjs create",
     "inspect:update": "node inspect-contracts.mjs update",
-    "inspect:reload": "node inspect-contracts.mjs extension-reload"
+    "inspect:reload": "node inspect-contracts.mjs extension-reload",
+    "parse:receipt": "node parse-receipt.mjs"
   }
 }

package/docs/examples/sdk-contract-consumer/parse-receipt.mjs

@@ -0,0 +1,22 @@
+import { spawnSync } from "node:child_process";
+import { parseMutationReceipt } from "@unbrained/pm-cli/sdk";
+
+const completed = spawnSync(
+  "pm",
+  ["create", "SDK receipt example", "--type", "Task", "--json"],
+  { encoding: "utf8", env: { ...process.env, NO_COLOR: "1" } },
+);
+
+if (completed.error) {
+  throw new Error(`Failed to run pm create: ${completed.error.message}`, {
+    cause: completed.error,
+  });
+}
+if (completed.status !== 0) {
+  throw new Error(
+    completed.stderr.trim() || `pm create failed with ${completed.status}`,
+  );
+}
+
+const receipt = parseMutationReceipt(completed.stdout);
+process.stdout.write(`${JSON.stringify(receipt, null, 2)}\n`);

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.4",
+  "version": "2026.8.6",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,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 && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 127 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && 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",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && 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",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -130,6 +130,7 @@
     "quality:retrieval-eval": "pnpm build && node scripts/release/retrieval-eval-gate.mjs",
     "quality:retrieval-eval:update": "pnpm build && node scripts/release/retrieval-eval-gate.mjs --update",
     "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
+    "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
@@ -213,13 +214,13 @@
     "esbuild": "0.28.1",
     "eslint": "^10.8.0",
     "eslint-plugin-sonarjs": "^4.2.0",
-    "eslint-plugin-unicorn": "^72.0.0",
+    "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
     "greptile": "^3.3.1",
     "jscpd": "^5.0.14",
     "tsx": "^4.23.5",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.65.0",
+    "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10",
     "yaml": "^2.9.0"
   }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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.8.4",
+  "version": "2026.8.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

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 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.8.4",
+  "version": "2026.8.6",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

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

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