@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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +22 -0
- package/dist/cli/error-guidance.js +4 -8
- package/dist/cli/main.js +3 -2
- package/dist/cli/register-assurance.js +28 -17
- package/dist/cli-bundle/bundle-manifest.json +161 -161
- package/dist/cli-bundle/chunks/chunk-3ZMOWAFM.js +2 -0
- package/dist/cli-bundle/chunks/chunk-DEDU3DG7.js +196 -0
- package/dist/cli-bundle/chunks/chunk-DL5M5J3V.js +13 -0
- package/dist/cli-bundle/chunks/chunk-F7FJYGK3.js +8 -0
- package/dist/cli-bundle/chunks/{chunk-RBTK5EZV.js → chunk-HIUZVCMN.js} +2 -2
- package/dist/cli-bundle/chunks/chunk-IMGIN7R6.js +2 -0
- package/dist/cli-bundle/chunks/{chunk-WLAHPSOX.js → chunk-Q47C67TQ.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-BM5YJ2UW.js → chunk-QGTUPEU5.js} +52 -52
- package/dist/cli-bundle/chunks/chunk-TF3TPKPR.js +34 -0
- package/dist/cli-bundle/chunks/{chunk-KOQMGCTA.js → chunk-YLBAPY22.js} +50 -50
- package/dist/cli-bundle/chunks/{register-list-query-XPCJRUUD.js → register-list-query-4HIZ7EA3.js} +2 -2
- package/dist/cli-bundle/chunks/{register-mutation-4RJCBKRS.js → register-mutation-W64FZ5HN.js} +2 -2
- package/dist/cli-bundle/chunks/register-operations-C44ET7R5.js +2 -0
- package/dist/cli-bundle/chunks/{register-setup-LLHAKP2V.js → register-setup-634MFRXU.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-27N23W6M.js +31 -0
- package/dist/cli-bundle/focused-chunks/{chunk-YIAXMC3T.js → chunk-2JP7W7GO.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-2RI2FESN.js +4 -0
- package/dist/cli-bundle/focused-chunks/chunk-3BNVU6LC.js +8 -0
- package/dist/cli-bundle/focused-chunks/{chunk-KHM2CS2C.js → chunk-3DJSGWVB.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-2DALMVF7.js → chunk-6MLIRBLV.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-6XYLENDV.js +155 -0
- package/dist/cli-bundle/focused-chunks/chunk-CP4K4WFS.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-RWPAWUOT.js → chunk-E3AVJ655.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-5TAGTDRE.js → chunk-EBTNSFYE.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-KPSXVBDV.js → chunk-HC2OL2H2.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-GQW4BPUT.js → chunk-I75MANL7.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-ZMGWAYH7.js → chunk-IIS2FRKL.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-NFHFZH2Z.js +2 -0
- package/dist/cli-bundle/focused-chunks/chunk-OGC4XSBC.js +17 -0
- package/dist/cli-bundle/focused-chunks/{chunk-JAFRIWVF.js → chunk-OOYYKQWX.js} +4 -4
- package/dist/cli-bundle/focused-chunks/{chunk-KTLOKKCQ.js → chunk-PKPOZXLL.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-QDZUABWL.js +2 -0
- package/dist/cli-bundle/focused-chunks/chunk-QQX5TDFT.js +16 -0
- package/dist/cli-bundle/focused-chunks/{chunk-NYLOUPOB.js → chunk-TEZIXMTH.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-WEH6NSL6.js +18 -0
- package/dist/cli-bundle/main.js +13 -13
- package/dist/cli-bundle/sdk-authoring.js +1 -1
- package/dist/cli-bundle/sdk-contracts.js +1 -1
- package/dist/cli-bundle/sdk-core.js +42 -41
- package/dist/cli-bundle/sdk-governance.js +1 -1
- package/dist/cli-bundle/sdk-graph.js +1 -1
- package/dist/cli-bundle/sdk-merge.js +1 -1
- package/dist/cli-bundle/sdk-query.js +1 -1
- package/dist/cli-bundle/sdk-runtime.js +1 -1
- package/dist/cli-bundle/sdk-testing.js +1 -1
- package/dist/cli-bundle/sdk.js +2 -2
- package/dist/core/checkpoint/checkpoint-gc.js +7 -12
- package/dist/core/extensions/activation-summary-markdown.js +5 -4
- package/dist/core/extensions/activation-summary.d.ts +2 -0
- package/dist/core/extensions/activation-summary.js +6 -2
- package/dist/core/extensions/capability-usage.d.ts +1 -1
- package/dist/core/extensions/capability-usage.js +4 -3
- package/dist/core/extensions/contribution-inventory.d.ts +1 -0
- package/dist/core/extensions/contribution-inventory.js +6 -2
- package/dist/core/extensions/extension-registries.js +3 -2
- package/dist/core/extensions/extension-types.d.ts +83 -1
- package/dist/core/extensions/extension-types.js +3 -2
- package/dist/core/extensions/loader.d.ts +2 -8
- package/dist/core/extensions/loader.js +53 -144
- package/dist/core/extensions/registration-values.d.ts +43 -0
- package/dist/core/extensions/registration-values.js +210 -0
- package/dist/core/extensions/runtime-registrations.d.ts +3 -1
- package/dist/core/extensions/runtime-registrations.js +12 -2
- package/dist/core/fs/fs-utils.d.ts +2 -0
- package/dist/core/fs/fs-utils.js +7 -3
- package/dist/core/history/drift-cache.js +4 -3
- package/dist/core/history/drift-scan.js +5 -11
- package/dist/core/lock/lock-gc.js +8 -13
- package/dist/core/lock/lock.js +5 -4
- package/dist/core/search/vector-stores.js +6 -11
- package/dist/core/store/item-metadata-cache.js +4 -4
- package/dist/core/telemetry/runtime.d.ts +6 -0
- package/dist/core/telemetry/runtime.js +101 -30
- package/dist/sdk/agent/command-recovery.d.ts +2 -0
- package/dist/sdk/agent/command-recovery.js +10 -2
- package/dist/sdk/annotations.js +4 -4
- package/dist/sdk/cli-contracts/completeness.js +9 -3
- package/dist/sdk/cli-contracts/enum-contracts.d.ts +1 -1
- package/dist/sdk/cli-contracts/flag-contracts.js +6 -3
- package/dist/sdk/cli-contracts/schemas/assurance-definition.d.ts +32 -0
- package/dist/sdk/cli-contracts/schemas/assurance-definition.js +25 -2
- package/dist/sdk/cli-contracts/tool-parameter-tables.js +35 -5
- package/dist/sdk/cli-contracts/tool-schema.js +17 -2
- package/dist/sdk/comments.js +4 -3
- package/dist/sdk/compile-cache.js +4 -3
- package/dist/sdk/compose.d.ts +3 -1
- package/dist/sdk/compose.js +16 -2
- package/dist/sdk/context-signal-store.js +4 -3
- package/dist/sdk/extension/install-runtime.js +4 -4
- package/dist/sdk/extension/managed-state.js +4 -3
- package/dist/sdk/extension-contracts.d.ts +1 -1
- package/dist/sdk/flag-invocation-contracts.js +5 -6
- package/dist/sdk/generated/generated-error-code-catalog-part-1.js +14 -2
- package/dist/sdk/governance/assurance-action.d.ts +27 -3
- package/dist/sdk/governance/assurance-action.js +112 -28
- package/dist/sdk/governance/assurance-mutation-error.d.ts +7 -0
- package/dist/sdk/governance/assurance-mutation-error.js +25 -2
- package/dist/sdk/governance/assurance-presets.d.ts +54 -0
- package/dist/sdk/governance/assurance-presets.js +136 -0
- package/dist/sdk/governance/assurance-runtime.d.ts +4 -0
- package/dist/sdk/governance/assurance-runtime.js +109 -8
- package/dist/sdk/governance/assurance.d.ts +39 -0
- package/dist/sdk/governance/assurance.js +143 -4
- package/dist/sdk/governance/gc.js +5 -11
- package/dist/sdk/governance/health.js +5 -5
- package/dist/sdk/governance/validate.js +4 -4
- package/dist/sdk/graph/durable-cache.js +61 -3
- package/dist/sdk/graph/governance-contracts.d.ts +12 -0
- package/dist/sdk/graph/governance-contracts.js +27 -0
- package/dist/sdk/graph/governance.d.ts +30 -2
- package/dist/sdk/graph/governance.js +124 -5
- package/dist/sdk/guide.js +4 -4
- package/dist/sdk/index.d.ts +2 -1
- package/dist/sdk/index.js +4 -3
- package/dist/sdk/linked-artifacts.d.ts +2 -0
- package/dist/sdk/linked-artifacts.js +29 -4
- package/dist/sdk/merge/install.js +5 -4
- package/dist/sdk/query/activity.js +4 -3
- package/dist/sdk/relationship-history.js +5 -5
- package/dist/sdk/schema-migration.js +4 -4
- package/dist/sdk/test/execution.js +4 -4
- package/dist/sdk/workspace-memory.js +4 -4
- package/dist/sdk/workspace-snapshot.js +8 -14
- package/dist/sdk/workspace-transaction-gc.js +4 -9
- package/dist/sdk/workspace-transaction.js +4 -4
- package/dist/sdk/workspace.js +4 -3
- package/docs/ASSURANCE.md +154 -3
- package/docs/CONFIGURATION.md +2 -0
- package/docs/EXTENSIONS.md +11 -12
- package/docs/RELATIONSHIP_GRAPH.md +15 -0
- package/docs/SDK.md +17 -3
- package/docs/TESTING.md +24 -15
- package/marketplace.json +2 -2
- package/package.json +3 -3
- package/packages/pm-beads/package.json +1 -1
- package/packages/pm-calendar/package.json +1 -1
- package/packages/pm-command-kit/package.json +1 -1
- package/packages/pm-digital-twin/package.json +1 -1
- package/packages/pm-governance-audit/package.json +1 -1
- package/packages/pm-guide-shell/package.json +1 -1
- package/packages/pm-kanban/package.json +1 -1
- package/packages/pm-lifecycle-hooks/package.json +1 -1
- package/packages/pm-linked-test-adapters/package.json +1 -1
- package/packages/pm-search-advanced/package.json +1 -1
- package/packages/pm-templates/package.json +1 -1
- package/packages/pm-todos/package.json +1 -1
- package/packages/pm-vcs/package.json +1 -1
- package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
- package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
- package/sdk/public-surface.json +183 -33
- package/dist/cli-bundle/chunks/chunk-3PS7X6GS.js +0 -8
- package/dist/cli-bundle/chunks/chunk-7KL6KMWF.js +0 -13
- package/dist/cli-bundle/chunks/chunk-D55A5AEN.js +0 -33
- package/dist/cli-bundle/chunks/chunk-KIKDWECH.js +0 -196
- package/dist/cli-bundle/chunks/chunk-R76342NV.js +0 -2
- package/dist/cli-bundle/chunks/chunk-VLUQOIDT.js +0 -2
- package/dist/cli-bundle/chunks/register-operations-2OGISOVR.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-5OQIMELN.js +0 -155
- package/dist/cli-bundle/focused-chunks/chunk-ECADZMVC.js +0 -18
- package/dist/cli-bundle/focused-chunks/chunk-EJGXRA6B.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-FFGSZCPK.js +0 -16
- package/dist/cli-bundle/focused-chunks/chunk-ISKOBJCM.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-LGYK3NUF.js +0 -8
- package/dist/cli-bundle/focused-chunks/chunk-NBLUKITQ.js +0 -4
- package/dist/cli-bundle/focused-chunks/chunk-Q4T463SD.js +0 -31
- package/dist/cli-bundle/focused-chunks/chunk-QVZVY53N.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-UTEWXDEQ.js +0 -17
package/docs/EXTENSIONS.md
CHANGED
|
@@ -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": {
|
|
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
|
-
`
|
|
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 `
|
|
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)
|
|
274
|
-
[pm-kpftft](../.agents/pm/tasks/pm-kpftft.toon)
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
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
|
-
|
|
295
|
+
pm assurance run tracker-context-quality --trigger ci --dry-run --json
|
|
289
296
|
```
|
|
290
297
|
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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-digital-twin",
|
|
3
|
-
"version": "2026.8.
|
|
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,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.
|
|
4
|
+
"version": "2026.8.13",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "unbrained",
|
|
7
7
|
"url": "https://github.com/unbraind/pm-cli"
|