@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md

@@ -0,0 +1,106 @@
+# Trustworthy Context and Evidence Contracts
+
+Tracker: [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-rncuf7](../.agents/pm/issues/pm-rncuf7.toon), [pm-m0b7h8](../.agents/pm/issues/pm-m0b7h8.toon), [pm-wqhzhg](../.agents/pm/issues/pm-wqhzhg.toon)
+
+## Agent Quick Context
+
+Project management is context management. These contracts make absence, identity, composition, and mutation outcomes explicit across CLI, SDK, MCP, packages, and persisted history:
+
+- Assurance evaluates authoritative full item records, supports first-class field presence predicates, canonicalizes relationship aliases, fingerprints measurement definitions, and attributes writes through the normal detected-author chain.
+- Graph audit reports both counts and ratios: `edge_share_by_kind`, `semantic_edges`, and `semantic_edge_share` alongside the existing structural profile.
+- Every health check row carries `ok: boolean` beside its compatible `status: ok|warn` value, including brief, summary, skipped, and full projections.
+- Linked-test removal preserves commands containing commas or equals signs, offers a lossless 1-based index selector, reports `removed`, and refuses a zero-match removal.
+- Collection grammar recovery labels positional roles when noun-verb-object input is transposed, then provides the accepted object-first command.
+
+Use runtime contracts for the exact active surface:
+
+```bash
+pm contracts --command test --flags-only --json
+pm contracts --action test --schema-only --json
+pm health --summary --json
+pm graph audit --summary --json
+```
+
+## Assurance Predicates and Verdict Identity
+
+An item-field measurement must choose exactly one predicate:
+
+```json
+{
+  "id": "missing-tests",
+  "source": { "kind": "items", "field": "tests", "state": "missing" }
+}
+```
+
+```json
+{
+  "id": "priority-one",
+  "source": { "kind": "items", "field": "priority", "equals": 1 }
+}
+```
+
+`state: missing` covers absent properties, `null`, empty strings, and empty arrays. `state: present` is its complement. Explicit `equals: null` remains an exact-value predicate and is not conflated with missing configuration.
+
+Each measurement result carries `definition_fingerprint`; assertion verdicts copy it as `measurement_definition_fingerprint`. A stored verdict can therefore be joined to the exact declaration semantics that produced it. Older verdicts remain readable and are visibly legacy because the fingerprint field is absent.
+
+## Graph Composition
+
+`pm graph audit` uses deduplicated directed edges as the denominator:
+
+```json
+{
+  "edges": 12,
+  "edges_by_kind": { "parent": 4, "related": 6, "verifies": 2 },
+  "edge_share_by_kind": {
+    "parent": 0.3333333333333333,
+    "related": 0.5,
+    "verifies": 0.16666666666666666
+  },
+  "semantic_edges": 2,
+  "semantic_edge_share": 0.16666666666666666
+}
+```
+
+The semantic numerator is the sum of `discovered_from`, `incident_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
+
+## Health Row Predicate
+
+Every entry in `health.checks` has this stable shape:
+
+```json
+{ "name": "storage", "status": "ok", "ok": true, "details": {} }
+```
+
+`status` remains for compatibility and human rendering. `ok` is the direct machine predicate; it survives brief and summary projections. Assurance health sources accept either `field: status` or `field: ok` and normalize success to `0`, warning to `1`.
+
+## Lossless Linked-Test Removal
+
+List first when selecting an index:
+
+```bash
+pm test pm-example --list --json
+pm test pm-example --remove-index 2 --json
+```
+
+`--remove-index` is repeatable and uses the current 1-based list order. Exact identity selectors remain available:
+
+```bash
+pm test pm-example --remove "command=node -e 'console.log(\"left=right,still-command\")'" --json
+pm test pm-example --remove 'path=tests/example.spec.ts' --json
+```
+
+For `command=` and `path=`, everything after the first identity prefix is the value; commas and equals signs are not re-parsed as fields. A successful mutation reports `removed`; a selector matching nothing raises `linked_test_remove_no_match` with unmatched selectors and a list-first recovery instead of returning a false-success no-op.
+
+## Collection Grammar Recovery
+
+Collection mutations use object-first grammar:
+
+```bash
+pm notes pm-example --add "context"
+pm comments pm-example --add "reviewed"
+pm files pm-example --add path=src/example.ts
+pm docs pm-example --add path=docs/example.md
+pm test pm-example --add 'command=pnpm test'
+```
+
+Inputs such as `pm notes add pm-example --note context` are refused as a transposed `add` subcommand. Structured recovery reports `transposed_subcommand=add` and `item_id=pm-example`, then supplies `pm notes pm-example --add context`. The visible notes `--note` alias remains accepted for compatibility, but new automation should use canonical `--add`.

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -62,6 +62,7 @@ This file is generated from `PM_COMMAND_VISIBILITY_CONTRACTS`. Do not edit it ma
 | `stats` | full |
 | `health` | standard |
 | `validate` | core |
+| `assurance` | full |
 | `gc` | full |
 | `workspace` | full |
 | `contracts` | standard |

package/docs/performance/sdk-entrypoint-import-costs.md

@@ -1,13 +1,17 @@
 # SDK entrypoint import costs
 
-Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon).
+Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon) and
+[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon).
 
 This table measures fresh-process ESM import and module evaluation. The bare
 Node v26.5.0 process floor on linux/x64
 was 41 ms p50 (48 ms p95) across
 5 measured runs after one warm-up. Focused entrypoints are
 compared with the compatibility aggregate; negative reduction means the focused
-entrypoint was slower in this sample.
+entrypoint was slower in this sample. The gate admits the median measured run
+against the unchanged upper-bound budget and 30 ms scheduler margin. A single
+cold or descheduled process therefore cannot fail the gate, while a majority of
+over-budget samples still does; p95 remains visible as diagnostic evidence.
 
 | Package export | p50 | p95 | p50 above Node | Reduction vs aggregate |
 |---|---:|---:|---:|---:|

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.10"
+    "version": "2026.8.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": "2026.8.10",
+      "version": "2026.8.12",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.10",
+  "version": "2026.8.12",
   "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 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/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.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: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/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.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 && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json",
     "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",
@@ -198,7 +198,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@sentry/node": "10.69.0",
+    "@sentry/node": "10.70.0",
     "@toon-format/toon": "^4.1.1",
     "@types/node": ">=22",
     "commander": "^15.0.0",
@@ -211,17 +211,17 @@
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.2",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.10",
-    "esbuild": "0.28.1",
-    "eslint": "^10.8.0",
+    "esbuild": "0.28.2",
+    "eslint": "^10.8.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",
     "greptile": "^3.3.1",
     "jscpd": "^5.0.14",
-    "tsx": "^4.23.11",
+    "tsx": "^4.23.12",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

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

@@ -8,6 +8,7 @@ import type {
   ExtensionApi,
   GlobalOptions,
 } from "@unbrained/pm-cli/sdk";
+import { createUnknownSubcommandError } from "@unbrained/pm-cli/sdk";
 import {
   runTemplatesList as runTemplatesListPackage,
   runTemplatesSave as runTemplatesSavePackage,
@@ -53,9 +54,14 @@ function assertListInvocation(
 ): void {
   const unexpectedSubcommand = args.find((arg) => arg.trim().length > 0);
   if (unexpectedSubcommand) {
-    throw new Error(
-      `Unknown pm templates subcommand "${unexpectedSubcommand}". Allowed: list, save, show. Apply a saved template with pm create <type> <title> --template <name>.`,
-    );
+    throw createUnknownSubcommandError({
+      command_path: "templates",
+      token: unexpectedSubcommand,
+      allowed: ["list", "save", "show"],
+      message_suffix:
+        ". Apply a saved template with pm create <type> <title> --template <name>.",
+      examples: ["pm create <type> <title> --template <name>"],
+    });
   }
   const unexpectedOptions = optionKeys(options);
   if (unexpectedOptions.length > 0) {

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "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.10",
+  "version": "2026.8.12",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",