@unbrained/pm-cli 2026.7.16 → 2026.7.17

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.17"
   },
   "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.17",
       "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.17",
   "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.17",
   "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.17",
   "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.17",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-governance-audit/extensions/governance-audit/comments-audit.ts

@@ -15,6 +15,7 @@ import {
   type GlobalOptions,
   type ItemMetadata,
   type ItemStatus,
+  type ListedItem,
   type RuntimeStatusRegistry,
 } from "./sdk.ts";
 
@@ -171,10 +172,11 @@ export interface CommentsAuditHistoryRow {
   text: string;
 }
 
-function parseStatus(
+const parseStatus = (
   raw: string | undefined,
   statusRegistry: RuntimeStatusRegistry,
-): ItemStatus | undefined {
+): ItemStatus | undefined => {
+  /** Normalize one optional status filter against the active project schema. */
   if (raw === undefined) {
     return undefined;
   }
@@ -186,12 +188,13 @@ function parseStatus(
     );
   }
   return normalized;
-}
+};
 
-function parseNonNegativeInteger(
+const parseNonNegativeInteger = (
   raw: string | undefined,
   flag: string,
-): number | undefined {
+): number | undefined => {
+  /** Parse an optional count flag without accepting fractions or negative values. */
   if (raw === undefined) {
     return undefined;
   }
@@ -203,16 +206,20 @@ function parseNonNegativeInteger(
     );
   }
   return parsed;
-}
+};
 
-function limitComments(values: Comment[], latest: number): Comment[] {
+const limitComments = (values: Comment[], latest: number): Comment[] => {
+  /** Retain only the requested trailing comments while preserving chronology. */
   if (latest <= 0) {
     return [];
   }
   return values.slice(Math.max(0, values.length - latest));
-}
+};
 
-function toHistoryRows(items: CommentsAuditEntry[]): CommentsAuditHistoryRow[] {
+const toHistoryRows = (
+  items: CommentsAuditEntry[],
+): CommentsAuditHistoryRow[] => {
+  /** Flatten per-item comments into stable export rows with item context. */
   const rows: CommentsAuditHistoryRow[] = [];
   for (const item of items) {
     for (let index = 0; index < item.comments.length; index += 1) {
@@ -233,12 +240,13 @@ function toHistoryRows(items: CommentsAuditEntry[]): CommentsAuditHistoryRow[] {
     }
   }
   return rows;
-}
+};
 
-function ratioPercent(
+const ratioPercent = (
   numerator: number,
   denominator: number,
-): { ratio: number; percent: number } {
+): { ratio: number; percent: number } => {
+  /** Render a bounded ratio and percentage with deterministic precision. */
   if (denominator <= 0) {
     return {
       ratio: 0,
@@ -250,11 +258,12 @@ function ratioPercent(
     ratio: Number(ratio.toFixed(4)),
     percent: Number((ratio * 100).toFixed(2)),
   };
-}
+};
 
-function buildCommentsAuditSummary(
+const buildCommentsAuditSummary = (
   items: CommentsAuditEntry[],
-): CommentsAuditSummary {
+): CommentsAuditSummary => {
+  /** Aggregate comment coverage globally and by project item type. */
   const itemsScanned = items.length;
   const itemsWithComments = items.filter(
     (entry) => entry.comment_count > 0,
@@ -326,16 +335,19 @@ function buildCommentsAuditSummary(
     },
     by_type: byType,
   };
-}
+};
 
-function resolveCommentsAuditLimits(options: CommentsAuditOptions): {
+const resolveCommentsAuditLimits = (
+  options: CommentsAuditOptions,
+): {
   fullHistory: boolean;
   latest: number | undefined;
   limitItems: number | undefined;
-} {
+} => {
+  /** Reconcile history and item-limit aliases into one validated selection. */
   const fullHistory = options.fullHistory === true;
   const latestParsed = parseNonNegativeInteger(options.latest, "--latest");
-  if (fullHistory && latestParsed !== undefined) {
+  if ([fullHistory, latestParsed !== undefined].every(Boolean)) {
     throw new PmCliError(
       "--full-history cannot be combined with --latest",
       EXIT_CODE.USAGE,
@@ -346,27 +358,31 @@ function resolveCommentsAuditLimits(options: CommentsAuditOptions): {
     "--limit-items",
   );
   const limitItemsAlias = parseNonNegativeInteger(options.limit, "--limit");
-  if (
-    limitItemsPrimary !== undefined &&
-    limitItemsAlias !== undefined &&
-    limitItemsPrimary !== limitItemsAlias
-  ) {
+  const distinctItemLimits = new Set(
+    [limitItemsPrimary, limitItemsAlias].filter(
+      (value): value is number => value !== undefined,
+    ),
+  );
+  if (distinctItemLimits.size > 1) {
     throw new PmCliError(
       "--limit and --limit-items must match when both are provided",
       EXIT_CODE.USAGE,
     );
   }
+  let latest: number | undefined = latestParsed ?? 1;
+  if (fullHistory) latest = undefined;
   return {
     fullHistory,
-    latest: fullHistory ? undefined : (latestParsed ?? 1),
-    limitItems: limitItemsPrimary ?? limitItemsAlias,
+    latest,
+    limitItems: distinctItemLimits.values().next().value,
   };
-}
+};
 
-function toCommentsAuditEntry(
-  item: Awaited<ReturnType<typeof runList>>["items"][number],
+const toCommentsAuditEntry = (
+  item: ListedItem,
   latest: number | undefined,
-): CommentsAuditEntry {
+): CommentsAuditEntry => {
+  /** Project one complete list record into the bounded comments-audit shape. */
   const comments = item.comments ?? [];
   return {
     id: item.id,
@@ -378,36 +394,39 @@ function toCommentsAuditEntry(
     comment_count: comments.length,
     comments: latest === undefined ? comments : limitComments(comments, latest),
   };
-}
+};
 
-function buildCommentsAuditFilters(
+const buildCommentsAuditFilters = (
   options: CommentsAuditOptions,
   status: ItemStatus | undefined,
   limitItems: number | undefined,
   latest: number | undefined,
   fullHistory: boolean,
-): CommentsAuditResult["filters"] {
+): CommentsAuditResult["filters"] => {
+  /** Preserve active audit filters in a stable nullable response envelope. */
+  const toNullable = <Value>(value: Value | undefined): Value | null =>
+    value === undefined ? null : value;
   return {
-    status: status ?? null,
-    type: options.type ?? null,
-    tag: options.tag ?? null,
+    status: toNullable(status),
+    type: toNullable(options.type),
+    tag: toNullable(options.tag),
     priority: options.priority === undefined ? null : Number(options.priority),
-    parent: options.parent ?? null,
-    sprint: options.sprint ?? null,
-    release: options.release ?? null,
-    assignee: options.assignee ?? null,
-    assignee_filter: options.assigneeFilter ?? null,
-    limit_items: limitItems ?? null,
-    latest: latest ?? null,
+    parent: toNullable(options.parent),
+    sprint: toNullable(options.sprint),
+    release: toNullable(options.release),
+    assignee: toNullable(options.assignee),
+    assignee_filter: toNullable(options.assigneeFilter),
+    limit_items: toNullable(limitItems),
+    latest: toNullable(latest),
     full_history: fullHistory,
   };
-}
+};
 
 /** Implements run comments audit for the public runtime surface of this module. */
-export async function runCommentsAudit(
+export const runCommentsAudit = async (
   options: CommentsAuditOptions,
   global: GlobalOptions,
-): Promise<CommentsAuditResult> {
+): Promise<CommentsAuditResult> => {
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   const settings = await readSettings(pmRoot);
   const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
@@ -427,18 +446,17 @@ export async function runCommentsAudit(
       assignee: options.assignee,
       assigneeFilter: options.assigneeFilter,
       limit: limitItems === undefined ? undefined : String(limitItems),
+      full: true as const,
     },
     global,
   );
 
   const items = listed.items.map((item) => toCommentsAuditEntry(item, latest));
-  const rows = fullHistory ? toHistoryRows(items) : undefined;
   const latestRowCount = items.reduce(
     (sum, entry) => sum + entry.comments.length,
     0,
   );
-
-  return {
+  const result: CommentsAuditResult = {
     items,
     count: items.length,
     summary: buildCommentsAuditSummary(items),
@@ -450,14 +468,16 @@ export async function runCommentsAudit(
       fullHistory,
     ),
     export: {
-      mode: fullHistory ? "full_history" : "latest",
-      /* c8 ignore next -- rows is always materialized from toHistoryRows() when fullHistory=true. */
-      row_count: fullHistory ? (rows?.length ?? 0) : latestRowCount,
+      mode: "latest",
+      row_count: latestRowCount,
     },
-    ...(rows ? { rows } : {}),
     now: listed.now ?? nowIso(),
-    ...(listed.warnings && listed.warnings.length > 0
-      ? { warnings: listed.warnings }
-      : {}),
   };
-}
+  if (fullHistory) {
+    const rows = toHistoryRows(items);
+    result.rows = rows;
+    result.export = { mode: "full_history", row_count: rows.length };
+  }
+  if (listed.warnings?.length) result.warnings = listed.warnings;
+  return result;
+};