@unbrained/pm-cli 2026.8.12 → 2026.8.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (173) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +22 -0
  3. package/dist/cli/error-guidance.js +4 -8
  4. package/dist/cli/main.js +3 -2
  5. package/dist/cli/register-assurance.js +28 -17
  6. package/dist/cli-bundle/bundle-manifest.json +161 -161
  7. package/dist/cli-bundle/chunks/chunk-3ZMOWAFM.js +2 -0
  8. package/dist/cli-bundle/chunks/chunk-DEDU3DG7.js +196 -0
  9. package/dist/cli-bundle/chunks/chunk-DL5M5J3V.js +13 -0
  10. package/dist/cli-bundle/chunks/chunk-F7FJYGK3.js +8 -0
  11. package/dist/cli-bundle/chunks/{chunk-RBTK5EZV.js → chunk-HIUZVCMN.js} +2 -2
  12. package/dist/cli-bundle/chunks/chunk-IMGIN7R6.js +2 -0
  13. package/dist/cli-bundle/chunks/{chunk-WLAHPSOX.js → chunk-Q47C67TQ.js} +2 -2
  14. package/dist/cli-bundle/chunks/{chunk-BM5YJ2UW.js → chunk-QGTUPEU5.js} +52 -52
  15. package/dist/cli-bundle/chunks/chunk-TF3TPKPR.js +34 -0
  16. package/dist/cli-bundle/chunks/{chunk-KOQMGCTA.js → chunk-YLBAPY22.js} +50 -50
  17. package/dist/cli-bundle/chunks/{register-list-query-XPCJRUUD.js → register-list-query-4HIZ7EA3.js} +2 -2
  18. package/dist/cli-bundle/chunks/{register-mutation-4RJCBKRS.js → register-mutation-W64FZ5HN.js} +2 -2
  19. package/dist/cli-bundle/chunks/register-operations-C44ET7R5.js +2 -0
  20. package/dist/cli-bundle/chunks/{register-setup-LLHAKP2V.js → register-setup-634MFRXU.js} +2 -2
  21. package/dist/cli-bundle/focused-chunks/chunk-27N23W6M.js +31 -0
  22. package/dist/cli-bundle/focused-chunks/{chunk-YIAXMC3T.js → chunk-2JP7W7GO.js} +2 -2
  23. package/dist/cli-bundle/focused-chunks/chunk-2RI2FESN.js +4 -0
  24. package/dist/cli-bundle/focused-chunks/chunk-3BNVU6LC.js +8 -0
  25. package/dist/cli-bundle/focused-chunks/{chunk-KHM2CS2C.js → chunk-3DJSGWVB.js} +2 -2
  26. package/dist/cli-bundle/focused-chunks/{chunk-2DALMVF7.js → chunk-6MLIRBLV.js} +2 -2
  27. package/dist/cli-bundle/focused-chunks/chunk-6XYLENDV.js +155 -0
  28. package/dist/cli-bundle/focused-chunks/chunk-CP4K4WFS.js +2 -0
  29. package/dist/cli-bundle/focused-chunks/{chunk-RWPAWUOT.js → chunk-E3AVJ655.js} +2 -2
  30. package/dist/cli-bundle/focused-chunks/{chunk-5TAGTDRE.js → chunk-EBTNSFYE.js} +2 -2
  31. package/dist/cli-bundle/focused-chunks/{chunk-KPSXVBDV.js → chunk-HC2OL2H2.js} +2 -2
  32. package/dist/cli-bundle/focused-chunks/{chunk-GQW4BPUT.js → chunk-I75MANL7.js} +2 -2
  33. package/dist/cli-bundle/focused-chunks/{chunk-ZMGWAYH7.js → chunk-IIS2FRKL.js} +2 -2
  34. package/dist/cli-bundle/focused-chunks/chunk-NFHFZH2Z.js +2 -0
  35. package/dist/cli-bundle/focused-chunks/chunk-OGC4XSBC.js +17 -0
  36. package/dist/cli-bundle/focused-chunks/{chunk-JAFRIWVF.js → chunk-OOYYKQWX.js} +4 -4
  37. package/dist/cli-bundle/focused-chunks/{chunk-KTLOKKCQ.js → chunk-PKPOZXLL.js} +2 -2
  38. package/dist/cli-bundle/focused-chunks/chunk-QDZUABWL.js +2 -0
  39. package/dist/cli-bundle/focused-chunks/chunk-QQX5TDFT.js +16 -0
  40. package/dist/cli-bundle/focused-chunks/{chunk-NYLOUPOB.js → chunk-TEZIXMTH.js} +2 -2
  41. package/dist/cli-bundle/focused-chunks/chunk-WEH6NSL6.js +18 -0
  42. package/dist/cli-bundle/main.js +13 -13
  43. package/dist/cli-bundle/sdk-authoring.js +1 -1
  44. package/dist/cli-bundle/sdk-contracts.js +1 -1
  45. package/dist/cli-bundle/sdk-core.js +42 -41
  46. package/dist/cli-bundle/sdk-governance.js +1 -1
  47. package/dist/cli-bundle/sdk-graph.js +1 -1
  48. package/dist/cli-bundle/sdk-merge.js +1 -1
  49. package/dist/cli-bundle/sdk-query.js +1 -1
  50. package/dist/cli-bundle/sdk-runtime.js +1 -1
  51. package/dist/cli-bundle/sdk-testing.js +1 -1
  52. package/dist/cli-bundle/sdk.js +2 -2
  53. package/dist/core/checkpoint/checkpoint-gc.js +7 -12
  54. package/dist/core/extensions/activation-summary-markdown.js +5 -4
  55. package/dist/core/extensions/activation-summary.d.ts +2 -0
  56. package/dist/core/extensions/activation-summary.js +6 -2
  57. package/dist/core/extensions/capability-usage.d.ts +1 -1
  58. package/dist/core/extensions/capability-usage.js +4 -3
  59. package/dist/core/extensions/contribution-inventory.d.ts +1 -0
  60. package/dist/core/extensions/contribution-inventory.js +6 -2
  61. package/dist/core/extensions/extension-registries.js +3 -2
  62. package/dist/core/extensions/extension-types.d.ts +83 -1
  63. package/dist/core/extensions/extension-types.js +3 -2
  64. package/dist/core/extensions/loader.d.ts +2 -8
  65. package/dist/core/extensions/loader.js +53 -144
  66. package/dist/core/extensions/registration-values.d.ts +43 -0
  67. package/dist/core/extensions/registration-values.js +210 -0
  68. package/dist/core/extensions/runtime-registrations.d.ts +3 -1
  69. package/dist/core/extensions/runtime-registrations.js +12 -2
  70. package/dist/core/fs/fs-utils.d.ts +2 -0
  71. package/dist/core/fs/fs-utils.js +7 -3
  72. package/dist/core/history/drift-cache.js +4 -3
  73. package/dist/core/history/drift-scan.js +5 -11
  74. package/dist/core/lock/lock-gc.js +8 -13
  75. package/dist/core/lock/lock.js +5 -4
  76. package/dist/core/search/vector-stores.js +6 -11
  77. package/dist/core/store/item-metadata-cache.js +4 -4
  78. package/dist/core/telemetry/runtime.d.ts +6 -0
  79. package/dist/core/telemetry/runtime.js +101 -30
  80. package/dist/sdk/agent/command-recovery.d.ts +2 -0
  81. package/dist/sdk/agent/command-recovery.js +10 -2
  82. package/dist/sdk/annotations.js +4 -4
  83. package/dist/sdk/cli-contracts/completeness.js +9 -3
  84. package/dist/sdk/cli-contracts/enum-contracts.d.ts +1 -1
  85. package/dist/sdk/cli-contracts/flag-contracts.js +6 -3
  86. package/dist/sdk/cli-contracts/schemas/assurance-definition.d.ts +32 -0
  87. package/dist/sdk/cli-contracts/schemas/assurance-definition.js +25 -2
  88. package/dist/sdk/cli-contracts/tool-parameter-tables.js +35 -5
  89. package/dist/sdk/cli-contracts/tool-schema.js +17 -2
  90. package/dist/sdk/comments.js +4 -3
  91. package/dist/sdk/compile-cache.js +4 -3
  92. package/dist/sdk/compose.d.ts +3 -1
  93. package/dist/sdk/compose.js +16 -2
  94. package/dist/sdk/context-signal-store.js +4 -3
  95. package/dist/sdk/extension/install-runtime.js +4 -4
  96. package/dist/sdk/extension/managed-state.js +4 -3
  97. package/dist/sdk/extension-contracts.d.ts +1 -1
  98. package/dist/sdk/flag-invocation-contracts.js +5 -6
  99. package/dist/sdk/generated/generated-error-code-catalog-part-1.js +14 -2
  100. package/dist/sdk/governance/assurance-action.d.ts +27 -3
  101. package/dist/sdk/governance/assurance-action.js +112 -28
  102. package/dist/sdk/governance/assurance-mutation-error.d.ts +7 -0
  103. package/dist/sdk/governance/assurance-mutation-error.js +25 -2
  104. package/dist/sdk/governance/assurance-presets.d.ts +54 -0
  105. package/dist/sdk/governance/assurance-presets.js +136 -0
  106. package/dist/sdk/governance/assurance-runtime.d.ts +4 -0
  107. package/dist/sdk/governance/assurance-runtime.js +109 -8
  108. package/dist/sdk/governance/assurance.d.ts +39 -0
  109. package/dist/sdk/governance/assurance.js +143 -4
  110. package/dist/sdk/governance/gc.js +5 -11
  111. package/dist/sdk/governance/health.js +5 -5
  112. package/dist/sdk/governance/validate.js +4 -4
  113. package/dist/sdk/graph/durable-cache.js +61 -3
  114. package/dist/sdk/graph/governance-contracts.d.ts +12 -0
  115. package/dist/sdk/graph/governance-contracts.js +27 -0
  116. package/dist/sdk/graph/governance.d.ts +30 -2
  117. package/dist/sdk/graph/governance.js +124 -5
  118. package/dist/sdk/guide.js +4 -4
  119. package/dist/sdk/index.d.ts +2 -1
  120. package/dist/sdk/index.js +4 -3
  121. package/dist/sdk/linked-artifacts.d.ts +2 -0
  122. package/dist/sdk/linked-artifacts.js +29 -4
  123. package/dist/sdk/merge/install.js +5 -4
  124. package/dist/sdk/query/activity.js +4 -3
  125. package/dist/sdk/relationship-history.js +5 -5
  126. package/dist/sdk/schema-migration.js +4 -4
  127. package/dist/sdk/test/execution.js +4 -4
  128. package/dist/sdk/workspace-memory.js +4 -4
  129. package/dist/sdk/workspace-snapshot.js +8 -14
  130. package/dist/sdk/workspace-transaction-gc.js +4 -9
  131. package/dist/sdk/workspace-transaction.js +4 -4
  132. package/dist/sdk/workspace.js +4 -3
  133. package/docs/ASSURANCE.md +154 -3
  134. package/docs/CONFIGURATION.md +2 -0
  135. package/docs/EXTENSIONS.md +11 -12
  136. package/docs/RELATIONSHIP_GRAPH.md +15 -0
  137. package/docs/SDK.md +17 -3
  138. package/docs/TESTING.md +24 -15
  139. package/marketplace.json +2 -2
  140. package/package.json +3 -3
  141. package/packages/pm-beads/package.json +1 -1
  142. package/packages/pm-calendar/package.json +1 -1
  143. package/packages/pm-command-kit/package.json +1 -1
  144. package/packages/pm-digital-twin/package.json +1 -1
  145. package/packages/pm-governance-audit/package.json +1 -1
  146. package/packages/pm-guide-shell/package.json +1 -1
  147. package/packages/pm-kanban/package.json +1 -1
  148. package/packages/pm-lifecycle-hooks/package.json +1 -1
  149. package/packages/pm-linked-test-adapters/package.json +1 -1
  150. package/packages/pm-search-advanced/package.json +1 -1
  151. package/packages/pm-templates/package.json +1 -1
  152. package/packages/pm-todos/package.json +1 -1
  153. package/packages/pm-vcs/package.json +1 -1
  154. package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
  155. package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
  156. package/sdk/public-surface.json +183 -33
  157. package/dist/cli-bundle/chunks/chunk-3PS7X6GS.js +0 -8
  158. package/dist/cli-bundle/chunks/chunk-7KL6KMWF.js +0 -13
  159. package/dist/cli-bundle/chunks/chunk-D55A5AEN.js +0 -33
  160. package/dist/cli-bundle/chunks/chunk-KIKDWECH.js +0 -196
  161. package/dist/cli-bundle/chunks/chunk-R76342NV.js +0 -2
  162. package/dist/cli-bundle/chunks/chunk-VLUQOIDT.js +0 -2
  163. package/dist/cli-bundle/chunks/register-operations-2OGISOVR.js +0 -2
  164. package/dist/cli-bundle/focused-chunks/chunk-5OQIMELN.js +0 -155
  165. package/dist/cli-bundle/focused-chunks/chunk-ECADZMVC.js +0 -18
  166. package/dist/cli-bundle/focused-chunks/chunk-EJGXRA6B.js +0 -2
  167. package/dist/cli-bundle/focused-chunks/chunk-FFGSZCPK.js +0 -16
  168. package/dist/cli-bundle/focused-chunks/chunk-ISKOBJCM.js +0 -2
  169. package/dist/cli-bundle/focused-chunks/chunk-LGYK3NUF.js +0 -8
  170. package/dist/cli-bundle/focused-chunks/chunk-NBLUKITQ.js +0 -4
  171. package/dist/cli-bundle/focused-chunks/chunk-Q4T463SD.js +0 -31
  172. package/dist/cli-bundle/focused-chunks/chunk-QVZVY53N.js +0 -2
  173. package/dist/cli-bundle/focused-chunks/chunk-UTEWXDEQ.js +0 -17
@@ -29,6 +29,7 @@ pm install npm:package@1.2.3 --project
29
29
  pm install https://github.com/org/repo --project
30
30
  pm install --github org/repo/path --ref main --project
31
31
  ```
32
+
32
33
  Bundled first-party packages live under `packages/pm-*`:
33
34
 
34
35
  ```bash
@@ -38,6 +39,7 @@ pm install calendar --project
38
39
  pm install search-advanced --project
39
40
  pm install kanban --project
40
41
  ```
42
+
41
43
  `pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
42
44
 
43
45
  External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
@@ -52,6 +54,7 @@ pm install npm:pm-github --project
52
54
  pm package doctor --project --detail deep --trace
53
55
  pm github validate --repo owner/repo
54
56
  ```
57
+
55
58
  For `pm-github`, run `pm github validate --repo owner/repo` before mutating commands; write paths require `GITHUB_TOKEN`/`GH_TOKEN` or `gh auth login`.
56
59
 
57
60
  For ecosystem maintenance, use the reusable external package smoke harness after building `dist/`:
@@ -132,7 +135,11 @@ Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/p
132
135
  "process_spawn": false
133
136
  },
134
137
  "capabilities": ["commands"],
135
- "contributions": { "schema_version": 1, "commands": ["hello"], "command_handlers": ["hello"] },
138
+ "contributions": {
139
+ "schema_version": 1,
140
+ "commands": ["hello"],
141
+ "command_handlers": ["hello"]
142
+ },
136
143
  "activation": { "commands": ["hello"] }
137
144
  }
138
145
  ```
@@ -286,11 +293,9 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
286
293
  ## Runtime APIs
287
294
 
288
295
  Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
289
-
290
296
  ```ts
291
297
  import { defineExtension } from "@unbrained/pm-cli/sdk";
292
298
  ```
293
-
294
299
  Common APIs:
295
300
 
296
301
  - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
@@ -302,6 +307,7 @@ Common APIs:
302
307
  - `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions are merged into native CLI, MCP, and SDK workspace graph assembly. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface.
303
308
  - `api.registerMigration(definition)` adds schema migrations.
304
309
  - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
310
+ - `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
305
311
  - `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
306
312
  - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
307
313
  - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
@@ -312,15 +318,8 @@ Common APIs:
312
318
  - Registered command, importer, and exporter handlers receive `context.sdk`, a host-bound service bundle containing a native-action `PmClient`, `getItemAt`, and `openRelationshipEventStore`, alongside portable workspace coordinates. The client reuses the already-active extension schema context without recursively loading extensions, so package commands and data adapters can compose core lifecycle operations safely in CLI and SDK hosts.
313
319
  - An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
314
320
 
315
- The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only
316
- `hooks` and registers a default-inert `afterCommand` hook so authors can copy a
317
- safe lifecycle pattern without changing command output.
318
-
319
- If a package calls a `register*` API without declaring the required manifest
320
- capability, `pm package doctor --project --detail deep --trace` reports
321
- `extension_capability_missing:<name>:<capability>` and shows the exact capability
322
- to add before publishing.
323
-
321
+ The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only `hooks` and registers a default-inert `afterCommand` hook so authors can copy a safe lifecycle pattern without changing command output.
322
+ If a package calls a `register*` API without declaring the required manifest capability, `pm package doctor --project --detail deep --trace` reports `extension_capability_missing:<name>:<capability>` and shows the exact capability to add before publishing.
324
323
  Inline command flags require both `commands` and `schema` capabilities. Runtime schema changes should be verified with:
325
324
 
326
325
  ```bash
@@ -257,6 +257,21 @@ bounded deterministic samples, truncation, policy text, and safe remediation;
257
257
  the audit never invents an edge. Explicit isolate exemptions suppress policy
258
258
  findings without changing structural coverage metrics.
259
259
 
260
+ The audit profile also exposes graph-wide resilience and delivery-lineage
261
+ metrics. `articulation_points` and `bridge_edges` reuse the exact cut-structure
262
+ algorithm; outcome metrics count explicit `Milestone` titles beginning with
263
+ `Outcome milestone:` and follow only hierarchy or `implements` edges toward
264
+ them. Active and terminal populations are reported separately, with integer
265
+ basis-point rates and all-status reachable/unreachable totals; the explicit
266
+ outcome milestones are roots, not work subjects, and are excluded from those
267
+ populations. Rate or
268
+ all-status floors are lifecycle-stable; an absolute active-population floor is
269
+ invalid because completing reachable work legitimately moves it into the
270
+ terminal population. `finding_subjects_by_code` includes every known finding
271
+ code even when its population is zero, so assurance selectors never confuse a
272
+ clean class with a missing contract field. Generic `related` edges cannot
273
+ satisfy outcome reachability.
274
+
260
275
  ```ts
261
276
  import {
262
277
  assembleWorkspaceRelationshipGraph,
package/docs/SDK.md CHANGED
@@ -297,7 +297,7 @@ Command/action contract exports:
297
297
  - Remediation planning: `planRelationshipRemediation` (with `RelationshipRemediationPlan`, `RelationshipRemediationStep`, and operation/confidence/code contracts) derives exact dry-run `remove`/`retype`/`supersede`/`waive`/`investigate` proposals from governance-audit findings and witnessed redundancy rows — evidence-backed, confidence-rated, and never auto-applied.
298
298
  - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
299
299
  - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
300
- - Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations.
300
+ - Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, `assertLinkedArtifactMutationIsUnambiguous`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations. A transaction that resolves one path into both its add and remove sets fails before item or history mutation; split an intentional replacement into two commands so its context remains explicit.
301
301
  - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
302
302
  - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
303
303
  - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
@@ -317,7 +317,7 @@ Command/action contract exports:
317
317
  - Execution and diagnostics engines: `runTest`, `runLinkedTests`, `runTestAll`, `runStartBackgroundRun`, `runTestRunsList`, `runTestRunsStatus`, `runTestRunsLogs`, `runTestRunsStop`, `runTestRunsResume`, `runTestRunsWorker`, `runEval`, `runTelemetry`, and `runStats`. Their CLI modules are compatibility re-exports of SDK-owned implementations.
318
318
  - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
319
319
  - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
320
- - Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry` and `resolveMissingOptionPlaceholder` preserve attempted argv while deriving enum, boolean, and scalar recovery arity from flag contracts; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
320
+ - Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry`, `resolveMissingOptionPlaceholder`, and `resolveRecoveryCommandName` preserve attempted argv, derive enum/boolean/scalar recovery arity from flag contracts, and identify the actual command without mistaking a global option value for one; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
321
321
  - Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
322
322
  - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
323
323
  - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
@@ -512,7 +512,8 @@ loud with attributed events and authors.
512
512
  Tracked: [pm-jcvg](../.agents/pm/tasks/pm-jcvg.toon),
513
513
  [pm-2ler](../.agents/pm/issues/pm-2ler.toon),
514
514
  [pm-chyh](../.agents/pm/issues/pm-chyh.toon), and
515
- [pm-p9sc](../.agents/pm/issues/pm-p9sc.toon).
515
+ [pm-p9sc](../.agents/pm/issues/pm-p9sc.toon). Conflicting batch refusal is
516
+ tracked by [pm-c6urop](../.agents/pm/issues/pm-c6urop.toon).
516
517
 
517
518
  Custom tools can use the same domain primitives as the CLI without dispatching a
518
519
  command action. The direct functions accept the typed command options plus a
@@ -556,6 +557,13 @@ tool invoked from a nested package never records a path that changes meaning
556
557
  when another agent runs from the repository root. Root-layout trackers use the
557
558
  tracker directory itself as their workspace.
558
559
 
560
+ Add and remove sets are compared after invocation-root anchoring, slash
561
+ normalization, glob expansion, and requested migrations. If the same path is in
562
+ both sets, `runFiles`, `runDocs`, and `runLinkedArtifacts` throw
563
+ `PmCliError` code `linked_artifact_mutation_conflict` before calling the item
564
+ store. This contract deliberately refuses to guess whether replacement or
565
+ removal should win and guarantees that no item or history write is published.
566
+
559
567
  `runDeps` also projects missing `parent` and legacy `blocked_by` references as
560
568
  typed missing edges, alongside structured dependencies. Tree and graph payloads
561
569
  apply shared depth/node/edge/token bounds and expose deterministic truncation
@@ -3292,6 +3300,12 @@ interpreted as a missing input. Strict close validation reports missing
3292
3300
  resolution fields first and suggests a targeted `pm update` before retrying the
3293
3301
  original close invocation.
3294
3302
 
3303
+ Recovery help examples resolve their command through
3304
+ `resolveRecoveryCommandName`, which uses the same bootstrap grammar as the CLI.
3305
+ Global value flags such as `--pm-path <path>` may appear before or after the
3306
+ subcommand; their values are never exposed as inferred command names or help
3307
+ targets.
3308
+
3295
3309
  Unknown-option envelopes rank command paths that accept the rejected flag by
3296
3310
  shared vocabulary and include explicit total/truncation metadata. They are
3297
3311
  contract-discovery hints, not permission to change the requested operation.
package/docs/TESTING.md CHANGED
@@ -270,28 +270,37 @@ parsed `workflow_jobs`; validation requires the two sets to match exactly.
270
270
 
271
271
  ## Tracker Context-Quality Ratchets
272
272
 
273
- Tracked by [pm-ips23h](../.agents/pm/issues/pm-ips23h.toon) and
274
- [pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon).
275
-
276
- `scripts/release/tracker-measurements.json` turns measured tracker populations
277
- into reviewed, shrinking-only ceilings. Each declaration names its canonical
278
- pm owner and a selector over stored dependency kinds, validator warnings,
279
- graph-profile fields, or health-check severity. Open owners enforce their
280
- ceiling; terminal owners retire it. Validator warnings and health checks are
281
- exhaustive, so a newly observed class fails until it has a canonical owner and
282
- reviewed declaration.
273
+ Tracked by [pm-ips23h](../.agents/pm/issues/pm-ips23h.toon),
274
+ [pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon), and
275
+ [pm-4ok4ex](../.agents/pm/tasks/pm-4ok4ex.toon), with lifecycle-stable outcome
276
+ reachability owned by [pm-g4k74y](../.agents/pm/issues/pm-g4k74y.toon) and
277
+ [pm-bzmeaa](../.agents/pm/tasks/pm-bzmeaa.toon).
278
+
279
+ The SDK-owned assurance registry stores tracker context-quality measurements,
280
+ floors, ceilings, lifetimes, enforcement, and executable negative controls in
281
+ `.agents/pm/assurance.json`. The `tracker-context-quality` gate covers stored
282
+ relationship kinds, validator debt, health checks, graph findings, structural
283
+ cut points, and typed reachability to outcome milestones. One workspace
284
+ assurance context reuses identical graph, validate, and health evaluations, so
285
+ a broad gate has one authoritative snapshot without repeatedly rescanning it.
286
+ Outcome enforcement uses an all-status reachable population, unreachable
287
+ ceiling, and basis-point floor. Active and terminal populations remain
288
+ diagnostics: absolute per-lifecycle floors would mistake normal close or reopen
289
+ transitions for relationship loss.
283
290
 
284
291
  Run the same gate used by hosted CI:
285
292
 
286
293
  ```bash
287
294
  pnpm quality:tracker-measurements
288
- node scripts/release/tracker-measurement-gate.mjs --negative-control
295
+ pm assurance run tracker-context-quality --trigger ci --dry-run --json
289
296
  ```
290
297
 
291
- `--update` can only lower a ceiling. It refuses to write while any population
292
- has regressed or remains undeclared, so updating the baseline cannot absorb a
293
- failure. Dependency-kind regressions include the post-measurement item, target,
294
- author, timestamp, and mutation-source rows in the JSON receipt.
298
+ Every native assertion contains both a passing boundary case and an impossible
299
+ case that must fail. Changes flow through `pm assurance put`, which refuses a
300
+ weaker bound, scope, lifetime, or enforcement unless a verified Decision item
301
+ authorizes it. `scripts/release/gate-registry.json` separately inventories the
302
+ retired bespoke gate and gives every graph subcommand either a named automated
303
+ consumer or an explicit interactive-only classification.
295
304
 
296
305
  ## Agent Output Token Budgets
297
306
 
package/marketplace.json CHANGED
@@ -6,14 +6,14 @@
6
6
  },
7
7
  "metadata": {
8
8
  "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
9
- "version": "2026.8.12"
9
+ "version": "2026.8.13"
10
10
  },
11
11
  "plugins": [
12
12
  {
13
13
  "name": "pm-claude",
14
14
  "source": "./plugins/pm-claude",
15
15
  "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.",
16
- "version": "2026.8.12",
16
+ "version": "2026.8.13",
17
17
  "author": {
18
18
  "name": "unbrained",
19
19
  "url": "https://github.com/unbraind/pm-cli"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-cli",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "description": "Git-native project management CLI for humans and agents.",
5
5
  "type": "module",
6
6
  "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
120
120
  "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
121
121
  "lint:duplicates": "jscpd --config .jscpd.json",
122
122
  "lint:codefactor": "pnpm quality:static",
123
- "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",
123
+ "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 dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json && 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",
124
124
  "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
125
125
  "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
126
126
  "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -130,7 +130,7 @@
130
130
  "quality:retrieval-eval": "pnpm build && node scripts/release/retrieval-eval-gate.mjs",
131
131
  "quality:retrieval-eval:update": "pnpm build && node scripts/release/retrieval-eval-gate.mjs --update",
132
132
  "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
133
- "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
133
+ "quality:tracker-measurements": "pnpm build && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json",
134
134
  "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
135
135
  "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
136
136
  "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-beads",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for importing Beads JSONL records.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-calendar",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for calendar and agenda views.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-command-kit",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-digital-twin",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-governance-audit",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for governance audit and normalization workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-guide-shell",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for guide and shell completion workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-kanban",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-lifecycle-hooks",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package demonstrating safe lifecycle hook registration.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-linked-test-adapters",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for optional linked-test run management adapters and reporters.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-search-advanced",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-templates",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for reusable create templates.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-todos",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "First-party pm package for Todo markdown import and export.",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unbrained/pm-vcs-sdk-exemplar",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pm-claude",
3
3
  "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.",
4
- "version": "2026.8.12",
4
+ "version": "2026.8.13",
5
5
  "author": {
6
6
  "name": "unbrained",
7
7
  "url": "https://github.com/unbraind/pm-cli"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-codex",
3
- "version": "2026.8.12",
3
+ "version": "2026.8.13",
4
4
  "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
5
5
  "author": {
6
6
  "name": "unbrained",