@unbrained/pm-cli 2026.7.18 → 2026.7.19

package/docs/SDK.md

@@ -158,7 +158,8 @@ Command/action contract exports:
 - 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.
 - 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.
 - 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.
-- Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, bounded semantic traversal, policy-aware governance, and explainable context queries. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, bounded semantic traversal, policy-aware governance, and explainable context queries. `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. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- Atomic application transactions: `commitWorkspaceTransaction` coordinates ordered, idempotent item and relationship mutations under one workspace writer lock and a durable replay journal. Interrupted work resumes from step inspection; ordinary failures append reverse-order compensations without rewriting immutable histories.
 - Typed customization primitives on `PmClient`: `init`, `config`, `schema`, `schemaList`, `schemaShow`, `schemaAddType`, `schemaRemoveType`, `schemaAddStatus`, `schemaRemoveStatus`, `schemaAddField`, `schemaRemoveField`, `schemaListFields`, `schemaShowField`, `schemaApplyPreset`, `schemaInferTypes`, `schemaShowStatus`, `profile`, `profileList`, `profileShow`, `profileApply`, and `profileLint`
 - Workspace-scaffold primitives: `ensurePmGitignore` and `getPmGitignoreBlock` let custom tools apply the same idempotent runtime/search cache policy as `pm init` without importing CLI internals.
 - Customization primitive option/result contracts: `InitCommandOptions` / `InitResult`, `ConfigCommandOptions` / `ConfigResult`, `SchemaSubcommand` / `SchemaResult` / `SchemaInspectResult`, `SchemaListResult`, `SchemaShowResult`, `SchemaAddTypeResult`, `SchemaRemoveTypeResult`, `SchemaAddStatusResult`, `SchemaRemoveStatusResult`, `SchemaAddFieldResult`, `SchemaRemoveFieldResult`, `SchemaListFieldsResult`, `SchemaShowFieldResult`, `SchemaApplyPresetResult`, `SchemaAddTypeInferResult`, `SchemaShowStatusResult`, `ProfileSubcommand` / `ProfileResult`, `ProfileListResult`, `ProfileShowResult`, `ProfileApplyResult`, `ProfileLintResult`
@@ -465,6 +466,12 @@ error listing the available handler command paths. Because
 `registerImporter`/`registerExporter` register handlers under `"<name> import"` /
 `"<name> export"`, the same helper exercises importer and exporter handlers too.
 
+Production command contexts also expose `sdk`: a host-bound native-action
+`PmClient`, point-in-time `getItemAt`, and durable relationship-store factory.
+The host client deliberately reuses the current extension activation instead of
+recursively loading packages, preserving registered schema while avoiding
+activation-queue re-entry.
+
 The remaining runtime surfaces an extension can register have matching invoke
 helpers, so the "invoke" verb covers the whole command pipeline — not just
 command handlers:
@@ -775,6 +782,97 @@ Lifecycle convenience methods and the matching top-level functions (`create`,
 as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
 tools that need to own item state without spawning `pm`.
 
+### Atomic workspace transactions
+
+Tracked by [pm-4e12](../.agents/pm/features/pm-4e12.toon), with the VCS
+acceptance story [pm-8ngt](../.agents/pm/stories/pm-8ngt.toon).
+
+`commitWorkspaceTransaction` is the public unit-of-work primitive for domain
+commands that must coordinate several SDK mutations. A plan supplies a stable
+transaction id plus ordered steps. Each step can inspect its durable state,
+apply an idempotent forward mutation, and append an idempotent compensation.
+The coordinator serializes transaction writers with one workspace lock and
+persists `.agents/pm/transactions/sdk/<transaction-id>.json` after every step.
+Before invoking a pending step, it also persists that step's durable ownership
+marker. Recovery and compensation therefore distinguish mutations begun by
+this transaction from matching domain state that existed before the attempt.
+Steps that must restore prior values implement `prepareCompensation()`; its
+JSON-safe result is stored atomically with that ownership marker before
+`apply()` begins and is passed back to `compensate(data)` after a restart.
+`lockTtlSeconds` (default `30`) and `lockWaitMs` (default `3000`) let callers
+size the writer lease above their longest expected attempt and choose their
+contention budget; both must be positive integers.
+
+If a process stops between the domain write and the journal update, rerunning
+the same plan discovers the already-applied step and continues. An ordinary
+error switches the journal to compensation mode and runs applied steps in
+reverse order, limited to steps whose forward attempt was durably recorded.
+Compensations are new item-history or relationship events: the
+coordinator never deletes or rewrites immutable history. A crash during
+compensation resumes compensation before a new attempt begins.
+
+```ts
+import {
+  PmClient,
+  commitWorkspaceTransaction,
+  type WorkspaceTransactionStep,
+} from "@unbrained/pm-cli/sdk";
+
+const pmRoot = "/workspace/.agents/pm";
+const pm = new PmClient({ pmRoot, author: "billing-agent" });
+const steps: WorkspaceTransactionStep[] = [
+  {
+    id: "approve-invoice",
+    async inspect() {
+      const invoice = await pm.get("invoice-42", { depth: "deep" });
+      if (invoice.item.status === "approved")
+        return { state: "applied", result: { status: "approved" } };
+      if (invoice.item.status !== "open")
+        throw new TypeError("Invoice must be open before approval");
+      return { state: "pending" };
+    },
+    async apply() {
+      await pm.update("invoice-42", { status: "approved" });
+      return { status: "approved" };
+    },
+    async compensate() {
+      await pm.update("invoice-42", {
+        status: "open",
+        message: "Compensate interrupted invoice approval",
+      });
+    },
+  },
+];
+
+await commitWorkspaceTransaction({
+  pmRoot,
+  transactionId: "approve-invoice-42",
+  author: "billing-agent",
+  steps,
+});
+```
+
+Logical atomicity is defined at the journal/replay boundary: callers publish a
+successful domain result only after the journal reaches `committed`, while
+failed attempts converge to compensated domain state. The filesystem adapter is
+not a database MVCC layer, so raw readers that bypass the coordinator are not
+snapshot-isolated during the short forward/compensation window. Use stable step
+ids, deterministic event ids, state-based inspection, and append-only inverse
+events. A step may return `undefined` when it has no journal result to retain.
+The optional transition observer exposes `step_compensating` immediately before
+each inverse mutation, which supports telemetry and semantic failure injection
+without coupling tests to storage call counts.
+`WorkspaceTransactionInterruptedError` is reserved for deterministic
+crash-boundary tests and leaves the journal resumable instead of triggering the
+normal in-process compensation path.
+
+Extension commands receive the same coordinator as
+`context.sdk.commitWorkspaceTransaction(...)`, already bound to the invoking
+tracker root. The bundled `pm-vcs` merge command is the reference implementation:
+it commits the changeset lifecycle transition and `commits_to` relationship
+together, compensates both streams on failure, and resumes a crash or a
+previously compensated retry without package-private file access.
+
 Package and extension lifecycle convenience methods are the SDK primitive layer
 for custom PM tools that need to manage their own package surface without
 shelling out. Use `pm.packageList`, `pm.packageInstall`,
@@ -1529,6 +1627,9 @@ deriveExtensionCapabilities(blueprint); // ["commands", "parser", "schema"]
 The blueprint's record-keyed fields (`commandOverrides`, `flags`, `parsers`,
 `renderers`, `services`) map a routing key to its handler, mirroring the
 two-argument `api.register*` overloads; `hooks` groups the five lifecycle kinds.
+The array-valued `relationshipKinds` field registers application-defined graph
+semantics and contributes the `schema` capability just like `itemTypes`,
+`itemFields`, and `profiles`.
 `composeExtension` is a pure assembler: it does not validate definitions —
 per-surface contract enforcement stays in `api.register*` and the loader, so a
 malformed definition surfaces the same activation diagnostic as a hand-written

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.18",
+  "version": "2026.7.19",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.7.18",
+  "version": "2026.7.19",
   "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.7.18",
+  "version": "2026.7.19",
   "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.7.18",
+  "version": "2026.7.19",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-governance-audit/package.json

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

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.7.18",
+  "version": "2026.7.19",
   "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.7.18",
+  "version": "2026.7.19",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/GAP_REPORT.md

@@ -0,0 +1,31 @@
+# VCS exemplar SDK gap report
+
+> Tracker: [pm-xtrd](../../.agents/pm/features/pm-xtrd.toon), parent story [pm-8ngt](../../.agents/pm/stories/pm-8ngt.toon).
+
+This report evaluates the public SDK against one bounded foreign domain: a
+changeset/ref workflow. It is an acceptance report, not a proposal to turn pm
+core into Git.
+
+| VCS-domain need | Public primitive used | Result |
+| --- | --- | --- |
+| Domain entities | extension item types and fields | Complete: `Changeset` and `VcsRef` require no core change. |
+| Domain lifecycle | project profile statuses and workflows | Complete: draft, review, merge, and abandon are schema-owned. |
+| Domain verbs | `registerCommand` | Complete: seven structured commands share normal CLI/contracts rendering. |
+| Business rule | `beforeCommand` hook | Complete: merge requires an explicit reviewed affirmation. |
+| Current state | `PmClient` lifecycle/query methods | Complete: command handlers use the same mutation engine as CLI and MCP. |
+| Point-in-time state | `getItemAt` | Complete: any changeset history version or timestamp is reconstructed without file access. |
+| Immutable graph events | `RelationshipEventStore` | Complete: optimistic attributable JSONL events survive process restart. |
+| Streaming derived state | `RelationshipEventLog.stream/project` and durable equivalents | Complete in this change: bounded batches feed deterministic application projections. |
+| Custom graph semantics | `registerRelationshipKinds` and `RelationshipKindRegistry` | Complete: `commits_to` is validated at activation and carries direction, inverse, ordering, cardinality, lifecycle, aliases, and version. |
+| Extension-wide custom graph registration | active extension registry plus workspace graph assembly | Complete in this change: CLI, MCP, and SDK graph assembly merge active package definitions into the native ontology. |
+| Atomic multi-item + relationship commit | `commitWorkspaceTransaction` | Complete: merge uses the host-bound public SDK journal, deterministic step inspection, a workspace writer lock, and append-only item/relationship compensations with crash-resumable replay. |
+| Content-addressed objects, tree diff, network transport | out of scope | Product-specific VCS storage is intentionally not a universal pm primitive. |
+
+## Conclusion
+
+The SDK can express the bounded VCS domain without private imports. Custom
+relationship semantics now cross the full public boundary from extension
+activation into native workspace graph assembly, while the package-owned event
+store supplies durable replay and projections. The last explicit SDK waiver is
+closed by the public transaction coordinator; larger storage-index and scale
+work remains on the canonical `pm-ju83` lineage.

package/packages/pm-vcs/README.md

@@ -0,0 +1,62 @@
+# @unbrained/pm-vcs
+
+> Tracker: [pm-xtrd](../../.agents/pm/features/pm-xtrd.toon), acceptance story [pm-8ngt](../../.agents/pm/stories/pm-8ngt.toon), atomic SDK transactions [pm-4e12](../../.agents/pm/features/pm-4e12.toon), graph SDK [pm-ju83](../../.agents/pm/features/pm-ju83.toon).
+
+`pm-vcs` is the first deliberately non-project-management package in the
+first-party ecosystem. It proves that public pm SDK and extension contracts can
+model a small version-control domain without importing `src/core`, reading item
+files directly, or adding VCS policy to the core CLI.
+
+The exemplar provides:
+
+- `Changeset` and `VcsRef` custom item types;
+- `draft -> proposed -> merged|abandoned` domain lifecycle;
+- `vcs ref-create`, `vcs create`, `vcs propose`, `vcs merge`, `vcs abandon`,
+  `vcs show`, and `vcs log` commands;
+- a `beforeCommand` hook enforcing explicit reviewed-merge affirmation;
+- point-in-time changeset reconstruction through `getItemAt`;
+- a durable, optimistic, append-only `commits_to` relationship stream projected
+  through `RelationshipEventStore.project`;
+- a crash-resumable `commitWorkspaceTransaction` merge that coordinates item
+  lifecycle and relationship events with append-only compensation.
+
+## Install and stage the domain
+
+```bash
+pm install vcs --project
+pm profile apply vcs
+pm package doctor --project --isolated --detail deep --json
+pm contracts --command "vcs merge" --flags-only --json
+```
+
+The package registers live types and fields globally, so the manifest does not
+use narrow command activation. Applying the profile stages custom statuses and
+the `Changeset` transition graph idempotently.
+
+## End-to-end changeset flow
+
+```bash
+pm vcs ref-create main --author demo
+pm vcs create "Add durable projection" --ref <ref-id> --tree-hash sha256:abc --author demo
+pm vcs propose <changeset-id> --author demo
+pm vcs show <changeset-id> --at 1
+pm vcs merge <changeset-id> --ref <ref-id> --reviewed --author demo
+pm vcs log
+```
+
+`vcs show --at` reconstructs immutable item history. `vcs log` independently
+projects the package-owned relationship JSONL stream, proving that current item
+state and graph event state are both rebuildable from public SDK contracts.
+`vcs merge` publishes success only after its SDK transaction journal commits;
+ordinary failures compensate in reverse order, and retrying the same merge id
+resumes any interrupted forward or compensation phase.
+
+## Package boundary
+
+All runtime imports use `@unbrained/pm-cli/sdk`. The exemplar intentionally does
+not implement content-addressed object storage, a working tree, filesystem
+diffing, or a network protocol. Those are Git product features; this package
+tests the reusable context, lifecycle, history, graph, package, and policy
+primitives beneath them.
+
+See [GAP_REPORT.md](GAP_REPORT.md) for the concrete primitive assessment.