@unbrained/pm-cli 2026.8.12 → 2026.8.14

package/dist/sdk/test/execution.js

@@ -4,13 +4,13 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b40f54be-2d3e-5b98-9d49-cb8608a782f5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="76053150-cc55-57e0-80d6-369196284cd0")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
+import { isFileMissingError, pathExists } from "../../core/fs/fs-utils.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv, parseOptionalNumber, } from "../../core/item/parse.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -989,7 +989,7 @@ async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = fals
         if (typeof error === "object" &&
             error !== null &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return;
         }
         throw error;
@@ -1939,4 +1939,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=b40f54be-2d3e-5b98-9d49-cb8608a782f5
+//# debugId=76053150-cc55-57e0-80d6-369196284cd0

package/dist/sdk/workspace-memory.js

@@ -4,10 +4,10 @@
  * Builds compact, cursor-bound historical rollups for large workspaces.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2e225010-1b53-59e9-8188-dcbe4a4f7eb7")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ad77a79d-54da-55f1-8ac8-935366880d90")}catch(e){}}();
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileAbsentError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { normalizeStatusForRegistry } from "../core/item/status.js";
 import { stableStringify } from "../core/shared/serialization.js";
 import { readItemMetadataDerivedIndexState } from "../core/store/item-metadata-cache.js";
@@ -194,7 +194,7 @@ async function readPersistedWorkspaceMemory(filePath) {
         const missing = typeof error === "object" &&
             error !== null &&
             "code" in error &&
-            error.code === "ENOENT";
+            isFileAbsentError(error);
         return { snapshot: null, invalid: !missing };
     }
 }
@@ -316,4 +316,4 @@ export function searchWorkspaceMemoryReadResult(memory, query, limit = 5) {
     };
 }
 //# sourceMappingURL=workspace-memory.js.map
-//# debugId=2e225010-1b53-59e9-8188-dcbe4a4f7eb7
+//# debugId=ad77a79d-54da-55f1-8ac8-935366880d90

package/dist/sdk/workspace-snapshot.js

@@ -5,11 +5,11 @@
  * state while excluding clone-local caches, locks, and recovery journals.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="470bb466-4619-5c54-a154-186b7ef4a049")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="36aacc71-c5f5-56f1-85f4-28b2be5b02e2")}catch(e){}}();
 import crypto from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { appendWorkspaceAuditEvent } from "../core/history/workspace-history.js";
 import { acquireLock } from "../core/lock/lock.js";
 import { getLockPath } from "../core/store/paths.js";
@@ -205,12 +205,6 @@ function validateSnapshotTarget(target) {
         });
     }
 }
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 /**
  * Runs a bounded snapshot filesystem stage, converting host environment faults
  * into declared refusals.
@@ -250,7 +244,7 @@ async function readSnapshotJson(file, target) {
         return JSON.parse(await readFile(file, "utf8"));
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             throw workspaceSnapshotNotFound(target);
         }
         throw error;
@@ -261,7 +255,7 @@ async function removeSnapshotEntry(entry, target, recursive) {
         await rm(entry, { recursive });
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             throw workspaceSnapshotNotFound(target);
         }
         throw error;
@@ -335,7 +329,7 @@ export async function createWorkspaceSnapshot(pmRoot, options = {}) {
         deduplicated = objectStat.isDirectory();
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -392,7 +386,7 @@ export async function listWorkspaceSnapshots(pmRoot) {
     const objectNames = await readdir(path.join(store, "objects")).catch((error) => {
         if (error instanceof Error &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -400,7 +394,7 @@ export async function listWorkspaceSnapshots(pmRoot) {
     const referenceNames = await readdir(path.join(store, "refs")).catch((error) => {
         if (error instanceof Error &&
             "code" in error &&
-            error.code === "ENOENT") {
+            isFileMissingError(error)) {
             return [];
         }
         throw error;
@@ -609,4 +603,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=470bb466-4619-5c54-a154-186b7ef4a049
+//# debugId=36aacc71-c5f5-56f1-85f4-28b2be5b02e2

package/dist/sdk/workspace-transaction-gc.js

@@ -13,17 +13,12 @@
  * never breaks correctness.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a6c0aa24-501a-5e76-a669-91d125634cf1")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7df80849-51e1-5efa-b40a-b44088f941a9")}catch(e){}}();
+import { isFileMissingError } from "../core/fs/fs-utils.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
 const TERMINAL_JOURNAL_STATUSES = new Set(["committed", "compensated"]);
-function isErrno(error, code) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === code);
-}
 function readJournalStatusAndTimestamp(raw) {
     let parsed;
     try {
@@ -129,7 +124,7 @@ export async function runWorkspaceTransactionGc(pmRoot, options) {
             .sort((left, right) => left.localeCompare(right));
     }
     catch (error) {
-        if (isErrno(error, "ENOENT")) {
+        if (isFileMissingError(error)) {
             return result;
         }
         throw error;
@@ -152,4 +147,4 @@ export async function runWorkspaceTransactionGc(pmRoot, options) {
     return result;
 }
 //# sourceMappingURL=workspace-transaction-gc.js.map
-//# debugId=a6c0aa24-501a-5e76-a669-91d125634cf1
+//# debugId=7df80849-51e1-5efa-b40a-b44088f941a9

package/dist/sdk/workspace-transaction.js

@@ -5,11 +5,11 @@
  * mutation primitives without rewriting immutable item or relationship history.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d49ec604-c10c-5706-9d87-510845e55e1a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6ed4a26f-2ae2-556a-87db-56844108757f")}catch(e){}}();
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { acquireLock } from "../core/lock/lock.js";
-import { writeFileAtomic } from "../core/fs/fs-utils.js";
+import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
 import { nowIso } from "../core/shared/time.js";
 /**
  * Deliberate process-boundary interruption used by deterministic crash tests.
@@ -244,7 +244,7 @@ async function loadJournal(pmRoot, transactionId, stepIds) {
         if (error !== null &&
             typeof error === "object" &&
             "code" in error &&
-            error.code === "ENOENT")
+            isFileMissingError(error))
             return undefined;
         throw error;
     }
@@ -361,4 +361,4 @@ export async function commitWorkspaceTransaction(options) {
     }
 }
 //# sourceMappingURL=workspace-transaction.js.map
-//# debugId=d49ec604-c10c-5706-9d87-510845e55e1a
+//# debugId=6ed4a26f-2ae2-556a-87db-56844108757f

package/dist/sdk/workspace.js

@@ -4,7 +4,8 @@
  * Maintains repository-scaffold contracts shared by the public SDK and CLI.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bbfa5b19-d801-582a-98e8-0c4925dd57c0")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="89261a49-97e5-5ffc-a81c-2409f0b529cf")}catch(e){}}();
+import { isFileMissingError } from "../core/fs/fs-utils.js";
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { EXIT_CODE } from "../core/shared/constants.js";
@@ -107,7 +108,7 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
         current = await withGitignorePermissionRecovery(() => readFile(gitignorePath, "utf8"));
     }
     catch (error) {
-        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
             throw error;
         }
     }
@@ -125,4 +126,4 @@ export async function ensurePmGitignore(workspaceRoot, options = {}) {
     return { path: gitignorePath, changed: true };
 }
 //# sourceMappingURL=workspace.js.map
-//# debugId=bbfa5b19-d801-582a-98e8-0c4925dd57c0
+//# debugId=89261a49-97e5-5ffc-a81c-2409f0b529cf

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon)
 
 ## Agent Quick Context
 
@@ -12,6 +12,15 @@ Assurance turns project policy into three reusable SDK-owned declarations:
 
 Declarations live in `.agents/pm/assurance.json`. Every registry mutation and non-dry gate verdict is appended through the verified workspace history stream; never edit either file directly.
 
+`pm history _workspace --verify`, `pm validate`, and `pm health` verify both
+the hash chain and replay-to-disk agreement for every governed singleton. A
+valid chain paired with a different, missing, or unreadable singleton is still
+drift. SDK hosts can inspect that state with `inspectWorkspaceHistoryState`,
+adopt a reviewed out-of-band value only through
+`reconcileWorkspaceJsonHistory` with a terminal authorizing Decision, or
+replace it from a verified version with `restoreWorkspaceJsonFromHistory`.
+Both recovery paths append forward; neither rewrites the existing stream.
+
 ## Why Assurance Exists
 
 Project management is context management. A useful quality gate therefore needs more than a shell exit code: it must preserve what was measured, which population was judged, why a bound exists, who owns it, what changed the result, how expensive the evaluation was, and which immutable tree received the verdict.
@@ -36,6 +45,11 @@ Measurements support these built-in sources:
 
 Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
 
+One workspace context memoizes identical graph operations and the shared
+validate and health reports for its lifetime. A gate may therefore project many
+fields from one authoritative audit snapshot without multiplying full-workspace
+I/O or allowing concurrent assertions to observe different tracker states.
+
 An `items` source with `field` must declare exactly one predicate: `equals` (including an explicit `null`) or `state`. `state: missing` treats an absent property, `null`, an empty string, or an empty array as missing; `state: present` selects the complement. Workspace evaluation loads full item metadata, so `files`, `tests`, and `docs` selectors measure stored evidence rather than a light projection that omitted those collections.
 
 Assertions require exactly one polarity:
@@ -86,6 +100,152 @@ pm assurance remove gate release-readiness
 
 Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
 
+### Presets, derivation, and promotion
+
+List the four built-in project shapes, preview one as ordinary declarations, or apply it atomically:
+
+```bash
+pm assurance presets
+pm assurance presets software-delivery --owner pm-example
+pm assurance apply software-delivery --owner pm-example \
+  --message "Adopt the initial delivery evidence contract"
+```
+
+The preset creates measurements, assertions, and a gate in one audited transaction. Reapplying the same bundle is idempotent; an existing divergent id is refused rather than overwritten. The available shapes are `software-delivery`, `research`, `agent-evaluation`, and `operations`.
+
+Self-derivation observes active items without writing anything. Each proposal reports its active scope, population size, and observed missing-evidence ceiling. Persistence requires the explicit `--apply` flag:
+
+```bash
+pm assurance derive --owner pm-example
+pm assurance derive --owner pm-example --apply \
+  --message "Accept the observed evidence baseline"
+pm assurance promote derived-active-missing-tests-ceiling --enforcement warn
+pm assurance promote derived-active-missing-tests-ceiling --enforcement block
+```
+
+Derived assertions start at `observe`. Promotion is exactly one step (`observe` to `warn`, then `warn` to `block`) and each transition is an ordinary audited declaration mutation. There is no automatic promotion and no privileged preset execution path.
+
+## Extension Measurement Providers
+
+An extension opens the measurement vocabulary through `api.registerAssuranceMeasurementProvider`. The registration declares stable keys, parameter types, a coarse `low`/`medium`/`high` cost class, network use, a host timeout, and a resolver. It requires the `services` capability; a network provider must also declare `permissions.network: true` in `manifest.json`.
+
+This code-quality provider measures a local report without changing assertion or gate semantics:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerAssuranceMeasurementProvider({
+      id: "coverage",
+      keys: {
+        lines: {
+          value_type: "number",
+          parameters: { report: { type: "string", required: true } },
+        },
+      },
+      cost_class: "low",
+      network: false,
+      timeout_ms: 2_000,
+      async resolve({ parameters }) {
+        const report = JSON.parse(
+          await readFile(String(parameters.report), "utf8"),
+        ) as {
+          total: { lines: { pct: number } };
+        };
+        return { value: report.total.lines.pct, population_size: 1, cost: 1 };
+      },
+    });
+  },
+});
+```
+
+An evaluation package can expose episode reward on the same surface:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "agent-eval",
+  keys: {
+    "mean-reward": {
+      value_type: "number",
+      parameters: { suite: { type: "string", required: true } },
+    },
+  },
+  cost_class: "high",
+  network: false,
+  timeout_ms: 120_000,
+  async resolve({ parameters }) {
+    const result = await runFrozenEvaluation(String(parameters.suite));
+    return {
+      value: result.meanReward,
+      population_size: result.episodes,
+      cost: result.steps,
+      contributors: result.regressedScenarioIds,
+    };
+  },
+});
+```
+
+An external registry provider declares its network dependency explicitly:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "npm-registry",
+  keys: {
+    "dist-tag-count": {
+      value_type: "number",
+      parameters: { package: { type: "string", required: true } },
+    },
+  },
+  cost_class: "medium",
+  network: true,
+  timeout_ms: 5_000,
+  async resolve({ parameters }) {
+    const name = encodeURIComponent(String(parameters.package));
+    const response = await fetch(
+      `https://registry.npmjs.org/-/package/${name}/dist-tags`,
+    );
+    if (!response.ok) throw new Error(`registry returned ${response.status}`);
+    const tags = (await response.json()) as Record<string, string>;
+    return { value: Object.keys(tags).length, population_size: 1, cost: 10 };
+  },
+});
+```
+
+The corresponding measurement is ordinary registry data:
+
+```json
+{
+  "id": "published-tag-count",
+  "source": {
+    "kind": "provider",
+    "provider": "npm-registry",
+    "key": "dist-tag-count",
+    "parameters": { "package": "@example/tool" }
+  }
+}
+```
+
+A provider-backed gate must opt into every provider and each trigger's execution envelope. Omission refuses provider execution:
+
+```json
+{
+  "id": "release-readiness",
+  "assertion_ids": ["published-tag-count-ceiling"],
+  "triggers": ["ci", "scheduled"],
+  "provider_policy": {
+    "allowed_providers": ["npm-registry"],
+    "triggers": {
+      "ci": { "max_cost_class": "low", "allow_network": false },
+      "scheduled": { "max_cost_class": "medium", "allow_network": true }
+    }
+  }
+}
+```
+
+Before invocation the host verifies the provider allow-list, declared cost class, and network capability for the active trigger. It then validates key parameters and result shape, enforces the registered timeout, and charges the returned cost through the existing measurement ceiling. Extension tests must bind `PM_PATH` and `PM_GLOBAL_PATH` to temporary roots; never point provider fixtures at the repository tracker or a live service.
+
 ## SDK and MCP
 
 The reusable client exposes the same action grammar:
@@ -103,9 +263,9 @@ await pm.assurance({
 });
 ```
 
-For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. A host contributes provider measurements by passing stable resolver ids to `createAssuranceWorkspaceContext`; an absent resolver fails loudly. External adapters must enforce an appropriate timeout. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
 
-Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, or `verdicts`. Discover the current machine contract instead of copying parameter lists:
+Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, `verdicts`, `presets`, `apply`, `derive`, or `promote`. Discover the current machine contract instead of copying parameter lists:
 
 ```bash
 pm contracts --action assurance --schema-only --json

package/docs/COMMANDS.md

@@ -21,7 +21,29 @@ pm contracts --command <command> --flags-only --json
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-7nqo6b](../.agents/pm/issues/pm-7nqo6b.toon), and
-[pm-j1r8gl](../.agents/pm/issues/pm-j1r8gl.toon).
+[pm-j1r8gl](../.agents/pm/issues/pm-j1r8gl.toon). Universal command intent and
+default output-budget enforcement are tracked by
+[pm-5t33or](../.agents/pm/features/pm-5t33or.toon),
+[pm-s2h0mq](../.agents/pm/issues/pm-s2h0mq.toon),
+[pm-pmrae8](../.agents/pm/issues/pm-pmrae8.toon), and
+[pm-7i97c3](../.agents/pm/issues/pm-7i97c3.toon).
+
+### Universal read-output ceiling
+
+Every SDK-backed read has a format-aware default token ceiling discovered from
+`pm contracts`. Results already within that ceiling are returned unchanged, so
+the default adds no receipt overhead to ordinary reads. An oversized result is
+degraded deterministically through string compaction, row compaction, and a
+truthful omission envelope; automatic degradation adds `read_output` with
+`budget_source: default`, `budget_tokens`, the final estimate, and the applied
+compaction flags.
+
+Use `--output-budget <tokens>` to request a tighter per-call ceiling. Use
+`--output-budget unbounded` only when the caller deliberately accepts the full
+cost. This cost opt-out is distinct from command-local row controls such as
+`activity --unbounded`, which disable a row limit but do not disable the shared
+token ceiling. `--output-format json` and global `--json` select the declared
+JSON ceiling; TOON uses the smaller default agent ceiling.
 
 ## Command Families
 
@@ -1161,7 +1183,14 @@ Extension policy tokens are explicitly scoped by
 Project-governance setters use the separate `governance_contracts` value
 domains; in particular, workflow enforcement is `off|warn|strict`, not the
 extension policy token `enforce`.
-Use `pm contracts --summary --json` first when bootstrapping in a tight context window; it emits one command and terse intent per row before the agent requests heavier command-specific flags or schemas.
+Use `pm contracts --summary --json` first when bootstrapping in a tight context
+window. `command_summaries` contains exactly one row per advertised command
+path—including aliases and namespace children—with a meaningful intent plus
+`default_max_estimated_tokens` and the format-specific TOON/JSON ceilings.
+Package commands contribute their intent through command registration (falling
+back to the registered description), so agents never need a generic
+`Inspect flags.` placeholder. Request heavier command-specific flags or schemas
+only after selecting the exact path.
 
 ## Completion
 

package/docs/CONFIGURATION.md

@@ -156,6 +156,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 | `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
 | `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
 | `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Any other value is ignored and the context is inferred.                            |
+| `PM_TELEMETRY_HTTP_TIMEOUT_MS`        | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
 | `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
@@ -164,6 +165,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 Interaction rules:
 
 - `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` short-circuit everything, including OTLP export, regardless of the other knobs.
+- `PM_TELEMETRY_HTTP_TIMEOUT_MS` applies only to the detached flush worker in normal use. It covers DNS, each IPv4/IPv6 connection attempt, TLS, and response completion. The upper bound preserves the 60-second worker-lock safety margin across the sequential event and OTLP phases; it does not make foreground commands wait for the network.
 - OTLP span export only happens when telemetry is enabled, `PM_TELEMETRY_OTEL_DISABLED` is off, and a traces endpoint is configured. By default spans are persisted to a bounded queue and exported by the detached, unref'd flush worker so commands exit promptly even when the traces endpoint is unreachable. `PM_TELEMETRY_INLINE_FLUSH=1` is the explicit test-oriented exception that performs the flush inline.
 - `pm health --check-telemetry --json` surfaces flush and OTLP export diagnostics (`pending_otel_spans`, `last_otel_attempt_at`, `last_otel_success_at`, `last_otel_failure_at`, `last_otel_failure_error`) and the active `env_overrides` (including `telemetry_inline_flush` and `telemetry_source_context`) so agents can self-diagnose a stalled endpoint.
 - An explicit `PM_AUTHOR` override adds a privacy-preserving agent-identity dimension to `command_start`/`command_finish` events so overridden invocations can be segmented in dashboards without leaking the raw author string. At `redacted`/`max` capture the events carry `author_context_hash` — the same installation-id-keyed one-way SHA-256 used for `pm_root_hash`/`cwd_hash`, so the same author hashes consistently within an installation but differently across installations. At `minimal` capture only a boolean `has_author_context` is emitted. The raw `PM_AUTHOR` value is never exported.

package/docs/EXTENSIONS.md

@@ -29,6 +29,7 @@ pm install npm:package@1.2.3 --project
 pm install https://github.com/org/repo --project
 pm install --github org/repo/path --ref main --project
 ```
+
 Bundled first-party packages live under `packages/pm-*`:
 
 ```bash
@@ -38,6 +39,7 @@ pm install calendar --project
 pm install search-advanced --project
 pm install kanban --project
 ```
+
 `pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
@@ -52,6 +54,7 @@ pm install npm:pm-github --project
 pm package doctor --project --detail deep --trace
 pm github validate --repo owner/repo
 ```
+
 For `pm-github`, run `pm github validate --repo owner/repo` before mutating commands; write paths require `GITHUB_TOKEN`/`GH_TOKEN` or `gh auth login`.
 
 For ecosystem maintenance, use the reusable external package smoke harness after building `dist/`:
@@ -132,7 +135,11 @@ Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/p
     "process_spawn": false
   },
   "capabilities": ["commands"],
-  "contributions": { "schema_version": 1, "commands": ["hello"], "command_handlers": ["hello"] },
+  "contributions": {
+    "schema_version": 1,
+    "commands": ["hello"],
+    "command_handlers": ["hello"]
+  },
   "activation": { "commands": ["hello"] }
 }
 ```
@@ -286,11 +293,9 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 ## Runtime APIs
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
-
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 ```
-
 Common APIs:
 
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
@@ -302,6 +307,7 @@ Common APIs:
 - `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions are merged into native CLI, MCP, and SDK workspace graph assembly. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface.
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
+- `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
 - `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
 - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
 - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
@@ -312,15 +318,8 @@ Common APIs:
 - Registered command, importer, and exporter handlers receive `context.sdk`, a host-bound service bundle containing a native-action `PmClient`, `getItemAt`, and `openRelationshipEventStore`, alongside portable workspace coordinates. The client reuses the already-active extension schema context without recursively loading extensions, so package commands and data adapters can compose core lifecycle operations safely in CLI and SDK hosts.
 - An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
 
-The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only
-`hooks` and registers a default-inert `afterCommand` hook so authors can copy a
-safe lifecycle pattern without changing command output.
-
-If a package calls a `register*` API without declaring the required manifest
-capability, `pm package doctor --project --detail deep --trace` reports
-`extension_capability_missing:<name>:<capability>` and shows the exact capability
-to add before publishing.
-
+The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only `hooks` and registers a default-inert `afterCommand` hook so authors can copy a safe lifecycle pattern without changing command output.
+If a package calls a `register*` API without declaring the required manifest capability, `pm package doctor --project --detail deep --trace` reports `extension_capability_missing:<name>:<capability>` and shows the exact capability to add before publishing.
 Inline command flags require both `commands` and `schema` capabilities. Runtime schema changes should be verified with:
 
 ```bash