@unbrained/pm-cli 2026.7.14 → 2026.7.16

package/docs/SDK.md

@@ -38,6 +38,13 @@ 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/schema.ts`](../src/sdk/schema.ts)
+- [`src/sdk/relationships.ts`](../src/sdk/relationships.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/cli-contracts.ts`](../src/sdk/cli-contracts.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)
@@ -65,6 +72,9 @@ Common authoring exports:
 - `PM_CLI_EXPECTED_ERROR_NAME`
 - `createPmCliExpectedError`
 - `isPmCliExpectedError`
+- `suppressHostOutput` / `isHostOutputSuppressed` / `SUPPRESS_HOST_OUTPUT_MARKER`
+  for extension commands that already wrote streaming, binary, or otherwise
+  pre-rendered output and must prevent a second host render
 
 Registration builders (`define*`, zero-cost identity — see [Authoring Builders](#authoring-builders)):
 
@@ -110,9 +120,9 @@ Storage format-version exports (under `@unbrained/pm-cli/sdk/runtime`):
 Command/action contract exports:
 
 - `PmClient` / `runAction` (high-level in-process action execution for custom tools, bots, CI, and embedded runtimes)
-- Typed read primitives on `PmClient`: `get`, `list`, `search`, `context`, `next`, `aggregate`, and `stats`
+- Typed read primitives on `PmClient`: `get` (including `GetOptions.at` point-in-time reads), `list`, `search`, `context`, `next`, `aggregate`, and `stats`; direct `getItemAt` reconstructs a canonical historical document without mutation
 - Read primitive option/result contracts: `GetOptions` / `GetResult`, `ListOptions` / `ListResult`, `SearchOptions` / `SearchResult`, `ContextOptions` / `ContextResult`, `NextOptions` / `NextResult`, `AggregateOptions` / `AggregateResult`, `StatsCommandOptions` / `StatsResult`
-- Context relevance primitives: `defaultScoreContextCandidates`, `scoreContextCandidates`, `scoreContextCandidatesWithActiveExtensions`, `evaluateContextRanking`, `runContextEvaluationScenario`, `runContextEvaluationCorpus`, and `summarizeContextEvaluationReports`
+- 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`
@@ -120,11 +130,13 @@ Command/action contract exports:
 - 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).
 - 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`, and `gc`
-- Governance and maintenance option/result contracts: `ValidateCommandOptions` / `ValidateResult`, `RunHealthOptions` / `HealthResult`, `GcCommandOptions` / `GcResult`
+- 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.
 - 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`
@@ -164,6 +176,84 @@ const result = await pm.planMaterialize(created.plan.id, {
 
 `field` is repeatable and forwards `name=value` pairs through normal schema-aware create validation for every materialized child. Required-on-create fields remain mandatory. Each `materialized` entry includes `id`, `title`, `type`, `parent`, `tags`, and `from_step`, so an agent can confirm the created work without extra `get` calls.
 
+### Immutable history and rich item reads
+
+Tracked: [pm-4a7m](../.agents/pm/features/pm-4a7m.toon),
+[pm-hib1](../.agents/pm/features/pm-hib1.toon),
+[pm-y4z5](../.agents/pm/issues/pm-y4z5.toon), and
+[pm-x1g5](../.agents/pm/issues/pm-x1g5.toon).
+
+History rewrite ownership lives in the SDK. The CLI `history-redact`,
+`history-repair`, and `history-compact` modules are thin compatibility shims
+over `runHistoryRedact`, `runHistoryRepair` / `runHistoryRepairAll`, and
+`runHistoryCompact` / `runHistoryCompactBulk`. Applications normally use the
+typed `PmClient` methods (or matching top-level `historyRedact`,
+`historyRepair`, `historyRepairAll`, `historyCompact`, and
+`historyCompactBulk` helpers), while package authors can call the `run*`
+primitives when they already own `GlobalOptions`.
+
+```ts
+import { PmClient, getItemAt } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot, author: "records-agent" });
+
+// Normal get projection, reconstructed at a one-based version.
+const historical = await pm.get(itemId, {
+  at: "7",
+  fields: "id,title,status,body",
+});
+// historical.reconstructed === true
+// historical.as_of_version === 7
+
+// Direct canonical document primitive for a custom provenance/VCS interface.
+const snapshot = await getItemAt(itemId, "2026-07-01T12:00:00.000Z", {
+  pmRoot,
+});
+
+await pm.historyRedact(itemId, {
+  literal: ["private.example"],
+  replacement: "[redacted-host]",
+  dryRun: true,
+});
+await pm.historyRepairAll({ dryRun: true });
+await pm.historyCompactBulk({
+  scope: "closed",
+  allOver: 500,
+  dryRun: true,
+});
+```
+
+`getItemAt` and restore share `resolveHistoryTarget`, `applyHistoryPatch`, and
+`replayHistoryToTarget`: every patch is normalized, applied strictly, and
+checked against the recorded before/after hashes. The read primitive never
+acquires a lock, rewrites an item, appends history, or mutates a derived index.
+It returns the canonical `ItemDocument` plus `reconstructed`,
+`as_of_version`, `as_of_timestamp`, normalized target metadata, and the current
+stream length. Invalid and future targets throw `PmCliError` with a structured
+`context.valid_range`.
+
+The shared resolver accepts explicit caller policy: immutable reads reject
+timestamps after the final recorded entry, while restore preserves
+latest-entry-at-or-before semantics so a current wall-clock timestamp restores
+the latest available state. Restore also retains command-specific diagnostics.
+
+Generic reads also expose two composable SDK facets:
+
+- `buildItemSchedule` normalizes deadlines, reminders, and events into a stable
+  schedule projection with convenient earliest-event `start_at`, `end_at`, and
+  `location` aliases. `pm get` includes it at standard/deep depth and supports
+  narrow fields such as `schedule.start_at`.
+- `buildItemChildrenRollup` accepts metadata supplied by the persistent derived
+  index or a source scan and returns type-agnostic direct-child totals, active
+  counts, status groups, a deterministic id-sorted sample, and explicit
+  truncation/continuation metadata. The primitive caps input at
+  `MAX_CHILD_PROJECTION_ITEMS` (one million) and never guesses which schema
+  types are containers.
+
+The CLI automatically computes that workspace projection for container-oriented
+built-ins and custom types. Built-in leaf reads stay constant-cost unless the
+caller explicitly projects `children`; SDK consumers remain fully type-agnostic.
+
 ### Linked resources and dependency governance
 
 Tracked: [pm-jcvg](../.agents/pm/tasks/pm-jcvg.toon),
@@ -575,7 +665,13 @@ await pm.docs(created.item.id, {
   add: ["docs/SDK.md"],
   note: "authoring reference",
 });
-const graph = await pm.deps(created.item.id, { format: "graph" });
+const graph = await pm.deps(created.item.id, {
+  format: "context",
+  maxDepth: 3,
+  nodeLimit: 20,
+  edgeLimit: 40,
+  tokenBudget: 800,
+});
 const types = await pm.schemaList();
 const profiles = await pm.profileList();
 const validation = await pm.validate({ checkResolution: true });
@@ -664,6 +760,11 @@ tools. `pm.init` stages a tracker, `pm.config` reads/writes settings,
 methods list, inspect, apply, and lint project archetypes. These helpers let a
 package or app construct an opinionated project-management experience while
 staying on the same schema/profile primitives the CLI and MCP use.
+The schema mutation and inspection engine is owned by `src/sdk/schema.ts`; the
+CLI schema module is a presentation-compatible re-export. Embedded runtimes can
+therefore compose schema operations without importing CLI code, while CLI, MCP,
+and `PmClient` continue to share the same validation, locking, persistence, and
+result contracts.
 `pm.init` accepts `workspace` to initialize `<workspace>/.agents/pm`; path-target
 calls retain tracker-root semantics. `InitResult.target` exposes the resolved
 mode, tracker root, and optional workspace root, while every explicit-target
@@ -687,12 +788,16 @@ runtimes.
 ### Context relevance and evaluation
 
 Tracked by [pm-4k6b](../.agents/pm/features/pm-4k6b.toon),
-[pm-h3no](../.agents/pm/tasks/pm-h3no.toon), and
-[pm-atfm](../.agents/pm/features/pm-atfm.toon).
+[pm-h3no](../.agents/pm/tasks/pm-h3no.toon),
+[pm-atfm](../.agents/pm/features/pm-atfm.toon), and
+[pm-qyc6](../.agents/pm/issues/pm-qyc6.toon).
 
 `pm context` and `pm next` share the public deterministic relevance model.
 Candidate order is the structural baseline; normalized metadata signals add
 explainable weighted contributions. Package authors can call
+`buildItemContextRelevanceCandidates(items, { statusRegistry, now, author,
+semanticSimilarity })`
+to derive the exact built-in metadata signals, then call
 `scoreContextCandidates` with a scorer callback, while installed extensions can
 register the governed `context_relevance` service override. A malformed or
 throwing override degrades to the deterministic default and emits an
@@ -1085,7 +1190,9 @@ same list/default semantics as core flags:
   (`value_type ?? type`). An unrecognized value type is rejected at registration.
 - `list: true` makes a repeated, comma-joined flag accumulate into an array —
   parity with core list flags such as `--tags`. `--scope a,b --scope c` resolves
-  to `["a", "b", "c"]`, with each element coerced by `value_type`.
+  to `["a", "b", "c"]`, with each element coerced by `value_type`. Long and
+  short aliases share one accumulator, so `-s a --scope b,c --scope=d` preserves
+  command-line order as `["a", "b", "c", "d"]`.
 - `default` (a scalar, or an array of scalars for a `list` flag) is applied when
   the flag is omitted; for a `list` flag the default is flattened into the
   accumulated array exactly like a provided value — comma-joined strings (e.g.
@@ -1095,11 +1202,48 @@ same list/default semantics as core flags:
 
 ```ts
 api.registerFlags("report", [
-  { long: "--scope", value_type: "string", list: true, default: "all" },
+  {
+    long: "--scope",
+    short: "-s",
+    value_type: "string",
+    list: true,
+    default: "all",
+  },
   { long: "--limit", value_type: "number", default: 20 },
 ]);
 ```
 
+Dynamic extension commands follow the same end-of-options contract as core
+commands. Put `--` before variadic content that begins with a dash or resembles a
+pm flag: `pm query run -- RETURN -h --json`. Everything after the separator is
+delivered to the registered positional arguments unchanged.
+
+## Output Ownership
+
+Command handlers should normally return structured data and let the host select
+TOON, JSON, service, or registered renderer output. A renderer override returns a
+string when it owns the matching payload and `null` to fall back to native
+rendering. When a command must write directly — for example, a streaming export,
+binary response, or already-rendered protocol — return `suppressHostOutput()` so
+the CLI does not append a second payload:
+
+```ts
+import { suppressHostOutput } from "@unbrained/pm-cli/sdk";
+
+api.registerCommand({
+  name: "archive stream",
+  async run() {
+    await writeArchiveToStdout();
+    return suppressHostOutput({ records: 42 });
+  },
+});
+```
+
+The optional structured result remains available to command-result hooks,
+telemetry, and embedded hosts, while the CLI writes no host-rendered output. The
+marker is structural rather than identity-based, so separately installed
+packages and custom SDK-built hosts can exchange it safely.
+
 `registerItemFields` validates each declared field `type` against the canonical
 coercion kinds (`string`, `number`, `boolean`, `array`, `object`) at activation.
 A typo fails activation with a did-you-mean hint (e.g. `type: "strnig"` →
@@ -2104,6 +2248,9 @@ Treat `recovery.suggested_retry` as the first-choice deterministic replay comman
 
 - Keep handlers deterministic and JSON-like.
 - Return data, not pre-rendered terminal text, unless implementing a renderer or output service.
+- After directly writing streaming, binary, or pre-rendered output, return
+  `suppressHostOutput()` to make output ownership explicit and prevent duplicate
+  CLI rendering.
 - Keep service, renderer, and preflight overrides narrow. For `output_format`, return `context.payload`, `null`, or `undefined` for unrelated commands; for renderers, return `null` when the payload should fall back to native rendering.
 - Declare only capabilities in use.
 - Set `pm_min_version` when the package requires SDK or runtime behavior added after older pm releases.

package/docs/SDK_CUSTOMIZATION_PRIMITIVES.md

@@ -0,0 +1,79 @@
+# SDK Customization Primitives
+
+Tracked by [pm-3mna](../.agents/pm/features/pm-3mna.toon),
+[pm-cpja](../.agents/pm/features/pm-cpja.toon), and
+[pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon).
+
+The SDK owns the configuration, project-profile, initialization, and agent-guidance engines used by the CLI. Package authors and embedded hosts can therefore compose those command families without spawning `pm` or importing their presentation adapters. Initialization still delegates optional bundled-package installation to the extension subsystem, so `runInit({ withPackages: true })` preserves the CLI's package lifecycle rather than duplicating it.
+
+## Public primitives
+
+```ts
+import {
+  applyInvocationAuthorOverride,
+  createPmCliProgram,
+  runConfig,
+  runInit,
+  runInitAgentGuidance,
+  runProfileApply,
+  runProfileLint,
+  runProfileList,
+  runProfileShow,
+  scanHistoryAuthorAttribution,
+} from "@unbrained/pm-cli/sdk";
+```
+
+The barrel also exports the corresponding option and result contracts, including `ConfigCommandOptions`, `ConfigResult`, `InitCommandOptions`, `InitResult`, `InitAgentGuidanceSummary`, `ProfileApplyCommandOptions`, and each profile result variant. The legacy `src/cli/commands/*` paths are compatibility re-exports; new integrations should use the SDK entrypoint.
+
+`createPmCliProgram(version)` creates a fresh Commander root with pm's universal global contract. It is suitable for embedded hosts that need the standard output, path, extension, profiling, and author flags before registering custom command families.
+
+## Invocation-wide author attribution
+
+Every command accepts a root-level author override:
+
+```bash
+pm --author release-agent create --title "Prepare release" --type Task
+pm update <id> --author review-agent --message "Address review feedback"
+```
+
+The override applies to every mutation performed during that invocation, including nested SDK-backed operations and extension hooks. Embedded hosts can use `applyInvocationAuthorOverride(author)` and call the returned idempotent restore function in `finally`; this prevents one request's identity from leaking into the next request in a long-lived process.
+
+Author precedence is:
+
+1. explicit command or invocation `--author`;
+2. `PM_AUTHOR`;
+3. project `author_default`;
+4. command-specific safe fallback.
+
+New trackers persist a non-empty `author_default`. `pm init --author <id>` and `PM_AUTHOR` take precedence; otherwise init derives a stable local `username@hostname` identity. Existing projects can configure the value without editing storage:
+
+```bash
+pm config project set author_default stable-agent-id
+```
+
+`scanHistoryAuthorAttribution(pmRoot)` reports missing or literal `unknown` authors in readable JSONL history streams with bounded samples. `pm health` and `pm validate` surface the same condition as an advisory warning. They never rewrite append-only history; remediation configures attribution for future mutations.
+
+## Custom initialization and profiles
+
+```ts
+import { runInit, runProfileApply } from "@unbrained/pm-cli/sdk";
+
+await runInit(
+  undefined,
+  { path: pmRoot },
+  {
+    defaults: true,
+    author: "bootstrap-agent",
+    typePreset: "ops",
+    agentGuidance: "add",
+  },
+);
+
+await runProfileApply("ops", { author: "profile-agent" }, { path: pmRoot });
+```
+
+These calls use the same schema scaffolding, settings validation, locks, hooks, templates, workspace cache policy, and deterministic result envelopes as their CLI equivalents. `runConfig` likewise exposes typed project/global get, set, list, and export behavior, while the profile read primitives let custom tools inspect catalog composition and lint extension-contributed profiles before applying them.
+
+## Import-boundary guarantee
+
+The CLI modules for config, init, init-agent-guidance, and profile contain compatibility exports only. The static quality gate removes their former private-core import allowances from the committed boundary baseline, so future presentation-layer logic cannot silently grow back into those command paths.

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.7.14",
+  "version": "2026.7.16",
   "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 --min-docstring-coverage 92.93 --min-exported-docstring-coverage 84.41 --min-member-docstring-coverage 13.655 && node scripts/release/audit-package-boundary.mjs && node scripts/release/token-budget-gate.mjs",
+    "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: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",
@@ -148,6 +148,7 @@
     "fast-json-patch": "^3.1.1"
   },
   "devDependencies": {
+    "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.0",
     "@types/node": "^22.20.1",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.7.14",
+  "version": "2026.7.16",
   "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.14",
+  "version": "2026.7.16",
   "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.14",
+  "version": "2026.7.16",
   "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/runtime-utils.ts

@@ -1,11 +1,12 @@
+/**
+ * @module pm-governance-audit/runtime-utils
+ *
+ * Shared parsing, comparison, linked-artifact, and result-decoration helpers
+ * for the governance-audit extension runtime.
+ */
 import { EXIT_CODE, PmCliError, PmClient, type ListOptions } from "./sdk.ts";
 
-export const DEFAULT_CLOSURE_LIKE_METADATA_FIELD_PATTERNS = {
-  blocked_reason: ["no active blocker because work is closed", "work is closed"],
-  resolution: ["closed with implementation evidence", "closed with verification evidence", "work completed and recorded", "work is closed"],
-  actual_result: ["closed and recorded", "work completed", "work completed and recorded"],
-} as const;
-
+/** Retain only list filters that the package-owned audit queries may forward. */
 export function buildListQueryFilters(
   filters: Pick<
     ListOptions,
@@ -21,18 +22,46 @@ export function buildListQueryFilters(
     | "release"
   >,
 ): ListOptions {
-  const { type, tag, priority, deadlineBefore, deadlineAfter, assignee, assigneeFilter, parent, sprint, release } = filters;
-  return { type, tag, priority, deadlineBefore, deadlineAfter, assignee, assigneeFilter, parent, sprint, release };
+  const {
+    type,
+    tag,
+    priority,
+    deadlineBefore,
+    deadlineAfter,
+    assignee,
+    assigneeFilter,
+    parent,
+    sprint,
+    release,
+  } = filters;
+  return {
+    type,
+    tag,
+    priority,
+    deadlineBefore,
+    deadlineAfter,
+    assignee,
+    assigneeFilter,
+    parent,
+    sprint,
+    release,
+  };
 }
 
+/** Order valid timestamps chronologically and malformed values lexicographically. */
 export function compareTimestampStrings(left: string, right: string): number {
   const leftMs = Date.parse(left);
   const rightMs = Date.parse(right);
-  if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return leftMs - rightMs;
+  if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs)
+    return leftMs - rightMs;
   return left.localeCompare(right);
 }
 
-export function jaccardSimilarity(leftTokens: string[], rightTokens: string[]): number {
+/** Measure set overlap between two token lists on the inclusive zero-to-one scale. */
+export function jaccardSimilarity(
+  leftTokens: string[],
+  rightTokens: string[],
+): number {
   if (leftTokens.length === 0 && rightTokens.length === 0) return 1;
   if (leftTokens.length === 0 || rightTokens.length === 0) return 0;
   const left = new Set(leftTokens);
@@ -42,48 +71,76 @@ export function jaccardSimilarity(leftTokens: string[], rightTokens: string[]):
   return intersection / new Set([...left, ...right]).size;
 }
 
+/** Trim, lowercase, and collapse internal whitespace for stable audit comparisons. */
 export function normalizeLowercaseWhitespace(value: string): string {
   return value.trim().toLowerCase().replace(/\s+/g, " ");
 }
 
+/** Split normalized text into non-empty lowercase ASCII alphanumeric tokens. */
 export function tokenizeAlphaNumeric(value: string): string[] {
-  return normalizeLowercaseWhitespace(value).split(/[^a-z0-9]+/).filter((token) => token.length > 0);
+  return normalizeLowercaseWhitespace(value)
+    .split(/[^a-z0-9]+/)
+    .filter((token) => token.length > 0);
 }
 
-export function parseIntegerLimit(raw: string | undefined, label = "--limit"): number | undefined {
+/** Parse an optional non-negative integer limit with package-specific error context. */
+export function parseIntegerLimit(
+  raw: string | undefined,
+  label = "--limit",
+): number | undefined {
   if (raw === undefined) return undefined;
   const parsed = Number(raw);
-  if (!Number.isInteger(parsed) || parsed < 0) throw new PmCliError(`${label} must be a non-negative integer`, EXIT_CODE.USAGE);
+  if (!Number.isInteger(parsed) || parsed < 0)
+    throw new PmCliError(
+      `${label} must be a non-negative integer`,
+      EXIT_CODE.USAGE,
+    );
   return parsed;
 }
 
+/** Normalize an optional comma-separated value into trimmed non-empty entries. */
 export function splitCommaList(raw: string | undefined | null): string[] {
   if (raw == null) return [];
-  return raw.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
 }
 
+/** Convert thrown values to a concise message suitable for audit result envelopes. */
 export function toErrorMessage(error: unknown): string {
   if (error instanceof Error) return error.message.trim() || error.name;
   return String(error);
 }
 
-export function toNonEmptyStringOrUndefined(value: unknown): string | undefined {
+/** Return trimmed non-empty text while rejecting non-string and blank values. */
+export function toNonEmptyStringOrUndefined(
+  value: unknown,
+): string | undefined {
   if (typeof value !== "string") return undefined;
   const normalized = value.trim();
   return normalized.length > 0 ? normalized : undefined;
 }
 
+/** Inputs used to attribute linked paths to every item that references them. */
 export interface LinkedArtifactAuditPayload {
+  /** Paths whose reverse-reference attribution should be reported. */
   paths?: string[];
+  /** Item identities and linked artifacts used to build the reverse index. */
   items?: Array<{ id: string; artifacts?: Array<{ path: string }> }>;
 }
 
+/** Deterministic reverse-reference summary for one linked artifact path. */
 export interface LinkedArtifactAuditEntry {
+  /** Linked artifact path described by this summary. */
   path: string;
+  /** Number of distinct items that reference the path. */
   linked_by_count: number;
+  /** Sorted distinct item ids that reference the path. */
   linked_item_ids: string[];
 }
 
+/** Build sorted, duplicate-free reverse attribution for requested artifact paths. */
 export function buildLinkedArtifactAudit(
   input: LinkedArtifactAuditPayload,
 ): LinkedArtifactAuditEntry[] {
@@ -175,7 +232,10 @@ export async function decorateGovernanceCommandResult(
   const result = asRecord(payload?.result);
   const options = payload?.options ?? {};
   if (!payload || !result) return payload?.result;
-  const linkedArtifactResult = await decorateLinkedArtifactResult(payload, result);
+  const linkedArtifactResult = await decorateLinkedArtifactResult(
+    payload,
+    result,
+  );
   if (linkedArtifactResult) return linkedArtifactResult;
 
   if (

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

@@ -1,3 +1,9 @@
+/**
+ * @module pm-governance-audit/sdk
+ *
+ * Resolves the host pm SDK runtime and exposes the typed subset consumed by
+ * the governance-audit package without copying core command implementations.
+ */
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import type * as RuntimeSdk from "@unbrained/pm-cli/sdk/runtime";
@@ -23,6 +29,7 @@ try {
 /* c8 ignore stop */
 const runtime = loadedRuntime;
 
+/** Host SDK values used by package-owned audit commands and runtime decorators. */
 export const {
   EXIT_CODE,
   PmCliError,
@@ -47,6 +54,7 @@ export const {
   runUpdate,
 } = runtime;
 
+/** Runtime status registry inferred from the host SDK's schema resolver. */
 export type RuntimeStatusRegistry = ReturnType<
   typeof resolveRuntimeStatusRegistry
 >;

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

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