@unbrained/pm-cli 2026.7.16 → 2026.7.18

package/docs/SDK.md

@@ -38,14 +38,37 @@ Source of truth:
 - [`src/sdk/files.ts`](../src/sdk/files.ts)
 - [`src/sdk/docs.ts`](../src/sdk/docs.ts)
 - [`src/sdk/dependencies.ts`](../src/sdk/dependencies.ts)
+- [`src/sdk/actionability.ts`](../src/sdk/actionability.ts)
 - [`src/sdk/schema.ts`](../src/sdk/schema.ts)
 - [`src/sdk/relationships.ts`](../src/sdk/relationships.ts)
+- [`src/sdk/graph/index.ts`](../src/sdk/graph/index.ts)
+- [`src/sdk/graph/assembly.ts`](../src/sdk/graph/assembly.ts)
+- [`src/sdk/graph/traversal.ts`](../src/sdk/graph/traversal.ts)
+- [`src/sdk/graph/analytics.ts`](../src/sdk/graph/analytics.ts)
+- [`src/sdk/graph/governance.ts`](../src/sdk/graph/governance.ts)
+- [`src/sdk/graph/remediation.ts`](../src/sdk/graph/remediation.ts)
+- [`src/sdk/graph/cache.ts`](../src/sdk/graph/cache.ts)
+- [`src/sdk/graph/run.ts`](../src/sdk/graph/run.ts)
 - [`src/sdk/relationship-history.ts`](../src/sdk/relationship-history.ts)
 - [`src/sdk/relationship-context.ts`](../src/sdk/relationship-context.ts)
 - [`src/sdk/governance/validate.ts`](../src/sdk/governance/validate.ts)
 - [`src/sdk/governance/health.ts`](../src/sdk/governance/health.ts)
 - [`src/sdk/governance/gc.ts`](../src/sdk/governance/gc.ts)
+- [`src/sdk/query/list.ts`](../src/sdk/query/list.ts)
+- [`src/sdk/query/search.ts`](../src/sdk/query/search.ts)
+- [`src/sdk/query/search-pagination.ts`](../src/sdk/query/search-pagination.ts)
+- [`src/sdk/query/search-rendering.ts`](../src/sdk/query/search-rendering.ts)
+- [`src/sdk/query/item-filter-options.ts`](../src/sdk/query/item-filter-options.ts)
+- [`src/sdk/query/parsers.ts`](../src/sdk/query/parsers.ts)
+- [`src/sdk/test/execution.ts`](../src/sdk/test/execution.ts)
+- [`src/sdk/test/batch.ts`](../src/sdk/test/batch.ts)
+- [`src/sdk/test/runs.ts`](../src/sdk/test/runs.ts)
+- [`src/sdk/test/parsers.ts`](../src/sdk/test/parsers.ts)
+- [`src/sdk/eval.ts`](../src/sdk/eval.ts)
+- [`src/sdk/telemetry.ts`](../src/sdk/telemetry.ts)
+- [`src/sdk/stats.ts`](../src/sdk/stats.ts)
 - [`src/sdk/cli-contracts.ts`](../src/sdk/cli-contracts.ts)
+- [`src/sdk/cli-bootstrap.ts`](../src/sdk/cli-bootstrap.ts)
 - [`src/sdk/cli-contracts/commander-types.ts`](../src/sdk/cli-contracts/commander-types.ts)
 - [`src/sdk/cli-contracts/commander-mutation-options.ts`](../src/sdk/cli-contracts/commander-mutation-options.ts)
 
@@ -125,18 +148,26 @@ Command/action contract exports:
 - Context relevance primitives: `buildItemContextRelevanceCandidates`, `defaultScoreContextCandidates`, `scoreContextCandidates`, `scoreContextCandidatesWithActiveExtensions`, `evaluateContextRanking`, `runContextEvaluationScenario`, `runContextEvaluationCorpus`, and `summarizeContextEvaluationReports`
 - Context relevance contracts: `ContextRelevanceCandidate`, `ContextRelevanceSignals`, `ContextRelevanceScorer`, `ContextRelevanceReport`, `ContextEvaluationReader`, `ContextEvaluationScenario`, `ContextEvaluationScenarioReport`, `ContextEvaluationThresholds`, and `ContextEvaluationCorpusReport`
 - Context packing and feedback primitives: `packContextCandidates`, `recordContextUsageServing`, `recordContextUsageTouch`, `recordContextUsageTouches`, and `readContextUsageAffinity`
-- Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, and `append`
+- Typed annotation and relationship primitives on `PmClient`: `comments`, `notes`, `learnings`, `files`, `filesDiscover`, `docs`, `deps`, `graph`, and `append`
+- Workspace graph-query runner: `runGraph` (with `GraphCommandOptions`, `GraphResult`, and per-subcommand envelopes) resolves the workspace relationship graph through the shared fingerprint-keyed cache and dispatches bounded `ancestors`/`descendants`/`predecessors`/`successors`/`paths`/`impact`/`analyze`/`audit`/`communities`/`redundancy`/`dominators`/`plan` queries with counts-first cost, truncation, and cache metadata; the `pm graph` CLI command and `pm_graph` MCP tool are thin adapters over it.
+- Structural graph analytics: `detectRelationshipCommunities` (deterministic label-propagation clustering with `maxIterations`/`minSize` bounds and convergence reporting), `findRedundantRelationshipEdges` (transitive-reduction scan that joins each directed ordering or hierarchy kind with its inverse spelling and returns witness paths), and `computeRelationshipDominators` (Cooper–Harvey–Kennedy immediate dominators with per-node gating weights for bottleneck ranking) — all deterministic, cancellable, and cost-metered like every other graph query.
+- Incremental graph cache: `WorkspaceGraphCache`, `workspaceGraphCache`, `resetWorkspaceGraphCache`, and `computeWorkspaceGraphFingerprint` reuse the assembled workspace graph and memoize deterministic query results under a fingerprint that digests every relationship-relevant item field (id, title, status and terminal classification, parent, legacy blocker, structured dependencies), so long-lived hosts stop paying full-workspace assembly per bounded query; `GraphCacheMetadata` reports assembly/result hit-or-miss on every `runGraph` envelope.
+- 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.
 - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
 - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
 - 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.
-- Dependency-governance primitive: `collectDanglingDependencyReferences` partitions 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`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, and bounded adjacency, closure, reverse-impact, shortest-path, induced-subgraph, and explainable context queries. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- 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).
 - 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`
 - Typed governance and maintenance primitives on `PmClient`: `validate`, `health`, `gc`, `historyRedact`, `historyRepair`, `historyRepairAll`, `historyCompact`, and `historyCompactBulk`
 - Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`, `HistoryRedactCommandOptions` / `HistoryRedactResult`, `HistoryRepairCommandOptions` / `HistoryRepairResult` / `HistoryRepairAllResult`, and `HistoryCompactCommandOptions` / `HistoryCompactResult` / `HistoryCompactBulkCommandOptions` / `HistoryCompactBulkResult`
 - Direct governance engines: `runValidate`, `runHealth`, and `runGc` are public SDK exports used by the CLI compatibility adapters and by custom policy engines that already own `GlobalOptions`. Their structured results are identical to CLI JSON output; no shell process or private core import is required.
+- 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.
+- Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
+- 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.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, and `upgrade`
@@ -147,6 +178,29 @@ Command/action contract exports:
 - `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`
 - `PM_TOOL_ACTION_PARAMETER_CONTRACTS`
 
+### Build an entire custom project tool
+
+The [SDK-only custom-tool exemplar](examples/sdk-custom-tool/README.md)
+is the acceptance reference for applications that use pm as a universal
+context engine rather than as an extension host. It imports only
+`@unbrained/pm-cli/sdk` and composes schema customization, custom workflow
+statuses, lifecycle mutations, annotations, linked resources, dependency
+graphs, bounded context, search, health, and validation into a standalone
+domain CLI.
+
+Copy its reusable client pattern when building a company workflow,
+domain-specific tracker, VCS-like system, or other application whose durable
+state and business rules fit pm's public primitives. Keep the executable layer
+thin: domain logic belongs in a reusable SDK client, while argv parsing and
+rendering stay at the edge.
+
+Embedded hosts can also import the SDK-owned bootstrap normalization primitives
+(`normalizeBootstrapInvocation`, `parseBootstrapGlobalOptions`, and related
+contracts) when they intentionally expose pm-compatible argv. Every
+`runPmCli()` call constructs a fresh Commander graph, so extension commands,
+extension flags, and runtime schema options from one workspace cannot leak into
+the next in-process invocation.
+
 ### Plan workflows
 
 Custom tools can manage durable plans without shelling out or importing CLI internals. The typed façade uses the same engine and result envelopes as `pm plan` and MCP `pm_plan`:
@@ -785,6 +839,87 @@ the same bounded maintenance engine as the CLI. Prefer these typed calls over
 shelling out when building CI, editor integrations, or long-running agent
 runtimes.
 
+### Query execution
+
+Tracked by [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) and the SDK boundary
+capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon).
+
+`runList` and `runSearch` are SDK-owned query engines, including filtering,
+projection, pagination, keyword and semantic ranking, extension-provider
+dispatch, and token-efficient response metadata. Their historical CLI module
+paths are identity-preserving compatibility exports, while `runEval` consumes
+the SDK search engine directly. Package authors can import these functions and
+their typed result contracts from `@unbrained/pm-cli/sdk` without importing CLI
+implementation modules.
+
+List result rows are modeled by projection: `ListFullResult` contains complete
+`ListedItem` records, tree ordering may enrich them with `ListTreeMetadata`, and
+compact or `fields` projections return `ListProjectedItem` dictionaries. Use
+`full: true` when an integration requires complete item metadata; the overload
+then returns `ListFullResult` without an assertion or cast.
+
+### Execution and diagnostics
+
+Tracked by [pm-oslr](../.agents/pm/features/pm-oslr.toon) and the SDK boundary
+capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon).
+
+Test execution, background-run supervision, search evaluation, telemetry
+inspection, and tracker statistics are SDK-owned primitives. A custom CI host or
+project-specific tool can compose the same sandboxing, context-preflight,
+deduplication, failure classification, progress, consent, and structured-result
+behavior as the CLI without spawning `pm` or importing `src/core` modules:
+
+```ts
+import {
+  runEval,
+  runTelemetry,
+  runTest,
+  runTestAll,
+  runTestRunsStatus,
+  type GlobalOptions,
+} from "@unbrained/pm-cli/sdk";
+
+const pmRoot = "/path/to/project/.agents/pm";
+const itemId = "pm-example";
+const runId = "test-run-example";
+const global: GlobalOptions = { path: pmRoot };
+
+const itemRun = await runTest(
+  itemId,
+  {
+    run: true,
+    autoPmContext: true,
+    checkContext: true,
+    failOnEmptyTestRun: true,
+  },
+  global,
+);
+
+const workspaceRun = await runTestAll(
+  { status: "open", autoPmContext: true, failOnSkipped: true },
+  global,
+);
+const background = await runTestRunsStatus(runId, global);
+const relevance = await runEval({ mode: "keyword", k: 10 }, global);
+const telemetry = await runTelemetry(
+  { subcommand: "stats", limit: 20 },
+  global,
+);
+```
+
+`runTest` and `runTestAll` always execute linked commands in isolated project and
+global tracker roots. `pm_context_mode`, run-level overrides, automatic tracker
+context, assertion requirements, empty-run detection, and failure categories are
+part of the SDK result contract rather than presentation-layer behavior.
+Background-run helpers return durable records and health/log projections; the
+host remains responsible for its own rendering and exit-code policy.
+
+`runTelemetry` retains consent and storage ownership inside the primitive:
+`status` and `stats` are observational, `flush` uses the consent-aware queue
+runtime, and `clear` disables telemetry and removes runtime artifacts. `runEval`
+uses the same live search path and unrounded gate decision as `pm eval`, returning
+compact rounded report metrics for stable machine output.
+
 ### Context relevance and evaluation
 
 Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon),
@@ -2226,6 +2361,7 @@ search degrades gracefully and emits warning codes instead of hard-failing.
 
 Runnable examples:
 
+- [SDK-only custom project tool](examples/sdk-custom-tool/README.md)
 - [SDK contract consumer](examples/sdk-contract-consumer/README.md)
 - [SDK app embedding](examples/sdk-app-embedding/README.md)
 - [CI examples](examples/ci/)

package/docs/SDK_PRIMITIVE_INVENTORY.md

@@ -1,6 +1,6 @@
 # SDK Primitive Inventory
 
-Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
+Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
 
 This inventory is the current SDK-first migration map for the principle `project management = context management`.
 The exact per-source CLI/MCP module inventory is checked in at [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk-import-boundary-baseline.json): each `allowed_private_core_imports[]` entry names one command, helper, or MCP source file and the private `src/core` modules it currently imports. The static quality gate reads that file and fails when `src/cli` or `src/mcp` adds a new private `src/core` import, uses a computed dynamic `import()` that cannot be ratcheted, or leaves a stale baseline entry after an import has been removed.
@@ -9,6 +9,7 @@ The exact per-source CLI/MCP module inventory is checked in at [`scripts/release
 
 - Boundary scope: `src/cli.ts`, `src/cli/**`, `src/mcp.ts`, and `src/mcp/**`.
 - Current scan size and private-edge counts are derived from [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk-import-boundary-baseline.json) and the `pnpm quality:static` ratchet output.
+- Current enforced baseline after the query/execution bundle: 51 CLI/MCP source modules and 412 private-core import edges, down from 62 sources and 538 edges at the start of the bundle.
 - Type-only imports and re-exports are intentionally counted because they still expose presentation layers to private core contracts.
 - Baseline owner: [pm-8778](../.agents/pm/tasks/pm-8778.toon).
 - Ratchet rule: SDK promotion PRs must shrink the baseline when they move a primitive behind `src/sdk`; no PR may grow it.
@@ -36,12 +37,13 @@ Use [`scripts/release/sdk-import-boundary-baseline.json`](../scripts/release/sdk
 | --- | --- | --- |
 | `create`, `update`, `update-many`, `copy`, `delete`, `restore` | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Item CRUD and replay paths should become typed lifecycle SDK calls. |
 | `claim`, `release`, `focus`, lifecycle shortcut helpers | [pm-98cz](../.agents/pm/features/pm-98cz.toon) | Ownership and actionable-state changes belong beside lifecycle primitives. |
-| `list`, `get`, `search`, `context`, `next`, `aggregate`, `stats` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | Read models should be reusable by CLI, MCP, and custom agents without shelling out. |
+| `list`, `get`, `search`, `context`, `next`, `aggregate`, `stats` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) | `list` and `search` implementations now live under `src/sdk/query/**`; remaining read models should follow the same SDK-owned pattern. |
 | `comments`, `notes`, `learnings`, `files`, `docs`, `deps`, `append` | [pm-zwpp](../.agents/pm/features/pm-zwpp.toon) | Annotation/link mutation semantics must be stable SDK primitives. |
 | `schema`, `config`, `profile`, `init`, `init-agent-guidance` | [pm-3mna](../.agents/pm/features/pm-3mna.toon) | Universal customization requires programmatic schema, profile, and config APIs. |
 | `history`, `activity`, `history-redact`, `history-repair`, `history-compact` | [pm-4a7m](../.agents/pm/features/pm-4a7m.toon) | Audited history read, activity, rewrite, and checkpoint operations need explicit public contracts. |
 | `plan` | [pm-je50](../.agents/pm/features/pm-je50.toon) | Plan harness operations should be usable by external orchestrators through SDK calls. |
-| `test`, `test-all`, `test-runs`, `eval`, `telemetry`, `reindex` | [pm-oslr](../.agents/pm/features/pm-oslr.toon) | Execution helpers should return typed run state and diagnostics instead of CLI-only text. |
+| `test`, `test-all`, `test-runs`, `eval`, `telemetry`, `stats` | [pm-oslr](../.agents/pm/features/pm-oslr.toon) | Implementations live under `src/sdk/test/**`, `src/sdk/eval.ts`, `src/sdk/telemetry.ts`, and `src/sdk/stats.ts`; CLI paths are compatibility exports with typed structured results. |
+| `reindex` | [pm-rjqr](../.agents/pm/features/pm-rjqr.toon) / [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon) | Search-index refresh remains part of the query/read ownership and terminal boundary burn-down. |
 | `extension`, `upgrade`, package lifecycle helpers | [pm-ugqx](../.agents/pm/epics/pm-ugqx.toon) | Existing package-author SDK surfaces stay public; package lifecycle can move behind SDK runtime helpers. |
 | `src/mcp/**` | [pm-usfg](../.agents/pm/epics/pm-usfg.toon) | MCP tools should call SDK primitives directly once each family is promoted. |
 

package/docs/examples/sdk-custom-tool/README.md

@@ -0,0 +1,27 @@
+# SDK-only custom project tool
+
+Tracked by [pm-cbwg](../../../.agents/pm/features/pm-cbwg.toon) and
+[pm-w89s](../../../.agents/pm/stories/pm-w89s.toon).
+
+This package is the end-to-end acceptance proof for pm's universal-tool goal.
+It is a standalone domain CLI, not an extension: its implementation imports
+only `@unbrained/pm-cli/sdk` and composes customization, lifecycle, query,
+context, annotation, linked-resource, relationship, and governance primitives.
+
+Run the acceptance suite, including the executable adapter contract, against
+fresh temporary workspaces:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/sdk/sdk-universal-tool-exemplar.spec.ts
+```
+
+The `pm-custom` flow registers a `Deliverable` type and `reviewing` status,
+creates a related parent/child graph, records comments/notes/learnings, links
+workspace evidence, reads list/search/context/dependency projections, closes
+the work with resolution evidence, and returns health/history verification as
+structured JSON. It never imports `src/core`, `src/cli`, or spawns `pm`.
+
+Use [src/index.ts](src/index.ts) as the copyable library pattern and
+[src/cli.ts](src/cli.ts) as the process-independent executable adapter. The
+package maps `pm-custom` to [src/entry.ts](src/entry.ts), which wires that
+adapter to Node.js arguments, author identity, output streams, and exit status.

package/docs/examples/sdk-custom-tool/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@unbrained/pm-sdk-custom-tool",
+  "version": "2026.7.16",
+  "private": true,
+  "type": "module",
+  "description": "SDK-only exemplar for building a complete custom project-management tool on pm primitives.",
+  "bin": {
+    "pm-custom": "src/entry.ts"
+  },
+  "peerDependencies": {
+    "@unbrained/pm-cli": ">=2026.7.16"
+  }
+}

package/docs/examples/sdk-custom-tool/src/cli.ts

@@ -0,0 +1,36 @@
+/**
+ * @module docs/examples/sdk-custom-tool/cli
+ *
+ * Runs the SDK-only exemplar as a small domain CLI.
+ */
+import {
+  runUniversalToolScenario,
+  type UniversalToolScenarioOptions,
+  type UniversalToolScenarioResult,
+} from "./index.ts";
+
+/** Scenario boundary accepted by the executable adapter. */
+export type UniversalToolScenarioRunner = (
+  options: UniversalToolScenarioOptions,
+) => Promise<UniversalToolScenarioResult>;
+
+/** Run the exemplar CLI against process-independent argument and I/O ports. */
+export async function runUniversalToolCli(
+  args: string[],
+  author: string | undefined,
+  writeOutput: (value: string) => void,
+  writeError: (value: string) => void,
+  runScenario: UniversalToolScenarioRunner = runUniversalToolScenario,
+): Promise<number> {
+  const workspace = args[0];
+  if (!workspace) {
+    writeError("Usage: pm-custom <workspace>\n");
+    return 2;
+  }
+  const result = await runScenario({
+    workspace,
+    author: author ?? "pm-sdk-custom-tool",
+  });
+  writeOutput(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}

package/docs/examples/sdk-custom-tool/src/entry.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * @module docs/examples/sdk-custom-tool/entry
+ *
+ * Connects the process-independent SDK exemplar adapter to Node.js process
+ * arguments, author identity, output streams, and exit status.
+ */
+import { runUniversalToolCli } from "./cli.ts";
+
+process.exitCode = await runUniversalToolCli(
+  process.argv.slice(2),
+  process.env.PM_AUTHOR,
+  (value) => process.stdout.write(value),
+  (value) => process.stderr.write(value),
+);

package/docs/examples/sdk-custom-tool/src/index.ts

@@ -0,0 +1,223 @@
+/**
+ * @module docs/examples/sdk-custom-tool
+ *
+ * Demonstrates a complete domain-specific project tool built only from the
+ * public pm SDK, without CLI or private-core imports.
+ */
+import path from "node:path";
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+/** Configuration for the SDK-only acceptance scenario. */
+export interface UniversalToolScenarioOptions {
+  /** Workspace whose `.agents/pm` tracker the exemplar owns. */
+  workspace: string;
+  /** Stable mutation author recorded in every scenario history event. */
+  author: string;
+}
+
+/** Structured proof returned by the SDK-only acceptance scenario. */
+export interface UniversalToolScenarioResult {
+  /** Registered domain item type. */
+  customType: "Deliverable";
+  /** Registered domain workflow status. */
+  customStatus: "reviewing";
+  /** Created parent deliverable id. */
+  projectId: string;
+  /** Created related child deliverable id. */
+  childId: string;
+  /** Final lifecycle state of the parent deliverable. */
+  projectStatus: string;
+  /** Author recorded by the public claim primitive. */
+  claimedBy: string;
+  /** Prior owner returned by the public release primitive. */
+  releasedPreviousAssignee: string | null;
+  /** Item ids returned by the typed list primitive. */
+  listedIds: string[];
+  /** Item ids returned by the typed search primitive. */
+  searchedIds: string[];
+  /** Active item count observed through bounded context before closeout. */
+  activeItemsBeforeClose: number;
+  /** Persisted comment count. */
+  commentCount: number;
+  /** Persisted private-note count. */
+  noteCount: number;
+  /** Persisted durable-learning count. */
+  learningCount: number;
+  /** Linked implementation-file count. */
+  linkedFileCount: number;
+  /** Linked documentation count. */
+  linkedDocCount: number;
+  /** Dependency edges returned by the graph projection. */
+  dependencyEdges: number;
+  /** Whether repository health remained clean. */
+  healthOk: boolean;
+  /** Whether the immutable history drift check passed. */
+  historyDriftOk: boolean;
+}
+
+/** Extract an id from a typed create result and fail with acceptance context. */
+export const requireCreatedId = (
+  result: { item?: { id?: unknown } },
+  label: string,
+): string => {
+  const id = result.item?.id;
+  if (typeof id !== "string" || id.length === 0) {
+    throw new Error(`SDK exemplar did not receive an id for ${label}.`);
+  }
+  return id;
+};
+
+/** Read a projected item id from compact, full, or scored search rows. */
+export const readProjectedItemId = (value: unknown): string | undefined => {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  if ("id" in value && typeof value.id === "string") {
+    return value.id;
+  }
+  if (
+    "item" in value &&
+    typeof value.item === "object" &&
+    value.item !== null &&
+    "id" in value.item &&
+    typeof value.item.id === "string"
+  ) {
+    return value.item.id;
+  }
+  return undefined;
+};
+
+/** Require the final item projection to contain its lifecycle status. */
+export const requireFinalStatus = (status: unknown): string => {
+  if (typeof status !== "string") {
+    throw new Error("SDK exemplar final project status is missing.");
+  }
+  return status;
+};
+
+/**
+ * Run a cross-domain SDK acceptance flow covering customization, lifecycle,
+ * context, annotations, linked resources, relationships, and governance.
+ */
+export async function runUniversalToolScenario(
+  options: UniversalToolScenarioOptions,
+): Promise<UniversalToolScenarioResult> {
+  const pmRoot = path.join(options.workspace, ".agents", "pm");
+  const client = new PmClient({
+    pmRoot,
+    cwd: options.workspace,
+    author: options.author,
+    noExtensions: true,
+  });
+
+  await client.init("work", { defaults: true, agentGuidance: "skip" });
+  await client.schemaAddStatus("reviewing", {
+    role: ["active"],
+    description: "Deliverable is undergoing domain review.",
+    order: 25,
+  });
+  await client.schemaAddType("Deliverable", {
+    description: "A domain deliverable managed by the SDK-only custom tool.",
+    defaultStatus: "open",
+    folder: "deliverables",
+    alias: ["deliverable"],
+  });
+
+  const projectId = requireCreatedId(
+    await client.create({
+      type: "Deliverable",
+      title: "Universal launch",
+      description: "Coordinate the SDK-only universal-tool acceptance flow.",
+      status: "open",
+      createMode: "progressive",
+    }),
+    "parent deliverable",
+  );
+  const childId = requireCreatedId(
+    await client.create({
+      type: "Deliverable",
+      title: "Ship contextual primitive",
+      description: "Prove a related child can be governed without the pm CLI.",
+      status: "open",
+      parent: projectId,
+      dep: [`id=${projectId},kind=related`],
+      createMode: "progressive",
+    }),
+    "child deliverable",
+  );
+  const claimed = await client.claim(projectId);
+  const released = await client.release(projectId);
+
+  const comment = await client.comments(projectId, {
+    add: "Public execution evidence belongs with the governed work.",
+  });
+  const note = await client.notes(projectId, {
+    add: "Private implementation rationale stays available to future agents.",
+  });
+  const learning = await client.learnings(projectId, {
+    add: "A domain tool can compose pm primitives without shelling out.",
+  });
+  const linkedFile = await client.files(projectId, {
+    add: ["README.md"],
+    note: "Custom workspace implementation surface",
+    validatePaths: true,
+  });
+  const linkedDoc = await client.docs(projectId, {
+    add: ["README.md"],
+    note: "Custom workspace documentation surface",
+    validatePaths: true,
+  });
+  await client.update(projectId, {
+    status: "reviewing",
+    message: "Enter custom review workflow",
+  });
+
+  const listed = await client.list({ noTruncate: true });
+  const searched = await client.search("Universal launch", {
+    noTruncate: true,
+  });
+  const context = await client.context({ limit: "10" });
+  const dependencyGraph = await client.deps(childId, { format: "graph" });
+
+  const resolution = {
+    resolution: "completed",
+    expectedResult: "SDK-only domain workflow completes with durable context.",
+    actualResult: "Customization, lifecycle, graph, and governance primitives passed.",
+  };
+  await client.close(childId, "SDK-only child acceptance completed.", resolution);
+  await client.close(projectId, "SDK-only universal-tool acceptance completed.", resolution);
+
+  const finalProject = await client.get(projectId, { full: true });
+  const health = await client.health({ checkOnly: true });
+  const validation = await client.validate({
+    checkResolution: true,
+    checkHistoryDrift: true,
+  });
+
+  return {
+    customType: "Deliverable",
+    customStatus: "reviewing",
+    projectId,
+    childId,
+    projectStatus: requireFinalStatus(finalProject.item.status),
+    claimedBy: claimed.claimed_by,
+    releasedPreviousAssignee: released.previous_assignee,
+    listedIds: listed.items
+      .map(readProjectedItemId)
+      .filter((id): id is string => id !== undefined),
+    searchedIds: searched.items
+      .map(readProjectedItemId)
+      .filter((id): id is string => id !== undefined),
+    activeItemsBeforeClose: context.summary.active_items,
+    commentCount: comment.count,
+    noteCount: note.count,
+    learningCount: learning.count,
+    linkedFileCount: linkedFile.count,
+    linkedDocCount: linkedDoc.count,
+    dependencyEdges: dependencyGraph.edge_count,
+    healthOk: health.ok,
+    historyDriftOk:
+      validation.checks.find((check) => check.name === "history_drift")
+        ?.status === "ok",
+  };
+}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.16",
+  "version": "2026.7.18",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -80,7 +80,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && node scripts/release/static-quality-gate.mjs --max-eslint-suppressions 158 --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/token-budget-gate.mjs",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 154 --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/token-budget-gate.mjs",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:context-eval": "node scripts/release/context-eval-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
@@ -151,12 +151,12 @@
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.0",
-    "@types/node": "^22.20.1",
+    "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "^4.1.9",
     "esbuild": "0.28.1",
     "eslint": "^10.6.0",
     "eslint-plugin-sonarjs": "^4.1.0",
-    "eslint-plugin-unicorn": "^70.0.0",
+    "eslint-plugin-unicorn": "^71.1.0",
     "greptile": "^3.1.1",
     "jscpd": "^5.0.11",
     "tsx": "^4.23.0",

package/packages/pm-beads/package.json

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