@unbrained/pm-cli 2026.8.13 → 2026.8.15

package/dist/sdk/read-output-rows.js

@@ -5,7 +5,23 @@
  * envelopes, including dot-delimited nested paths used by graph projections.
  */
 
-!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]="ae6fbd4a-6c4e-5639-93ac-f107a336e95b")}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]="0c69ff43-7bbc-5128-9533-bbf15365126b")}catch(e){}}();
+const BUDGET_METADATA_ROOT_KEYS = new Set([
+    "applied_bound",
+    "completeness",
+    "budget_retention_policy",
+    "continuation_contract",
+    "continuation_kind",
+    "continuation_path",
+    "filters",
+    "omission_receipt",
+    "output_budget_truncation",
+    "projection",
+    "read_output",
+    "read_session",
+    "row_contract",
+    "sorting",
+]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -35,6 +51,16 @@ function replaceValueAtPath(result, rowPath, replacement) {
     target[segments.at(-1)] = replacement;
     return root;
 }
+/** Replace one declared row collection with a suffix beginning at an offset. */
+export function sliceReadOutputRowCollection(result, rowPath, offset) {
+    const collection = readOutputRowCollections(result).find((entry) => entry.path === rowPath);
+    if (!collection)
+        return result;
+    const replacement = Array.isArray(collection.value)
+        ? collection.value.slice(offset)
+        : Object.fromEntries(Object.entries(collection.value).slice(offset));
+    return replaceValueAtPath(result, rowPath, replacement);
+}
 /** Resolve declared row paths, falling back to top-level array properties. */
 export function readOutputRowPaths(result) {
     const contract = result.row_contract;
@@ -54,6 +80,38 @@ export function readOutputRowCollections(result) {
             : [];
     });
 }
+/**
+ * Discover every collection the token-budget degradation ladder may reduce.
+ *
+ * Ordinary field and amount projections stay bound to declared row paths (or
+ * top-level array fallbacks), because a nested tag list is not an independent
+ * result row. Budget degradation has a different obligation: it must exhaust
+ * nested content collections before omitting the whole useful result. This
+ * census therefore adds nested arrays while excluding receipt/envelope metadata
+ * whose mutation would make the disclosure itself incomplete.
+ */
+export function readOutputBudgetCollections(result) {
+    const collections = readOutputRowCollections(result);
+    const declaredPaths = new Set(collections.map((collection) => collection.path));
+    const visit = (value, path) => {
+        if (Array.isArray(value)) {
+            if (!declaredPaths.has(path)) {
+                collections.push({ path, value });
+            }
+            value.forEach((entry, index) => visit(entry, `${path}.${index}`));
+            return;
+        }
+        if (!isRecord(value))
+            return;
+        for (const [key, entry] of Object.entries(value)) {
+            if (path.length === 0 && BUDGET_METADATA_ROOT_KEYS.has(key))
+                continue;
+            visit(entry, path.length === 0 ? key : `${path}.${key}`);
+        }
+    };
+    visit(result, "");
+    return collections;
+}
 /** Count array entries and object-map values across declared row collections. */
 export function countReadOutputRows(result) {
     return readOutputRowCollections(result).reduce((total, collection) => total +
@@ -97,4 +155,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=ae6fbd4a-6c4e-5639-93ac-f107a336e95b
+//# debugId=0c69ff43-7bbc-5128-9533-bbf15365126b

package/dist/sdk/runtime-input.js

@@ -5,7 +5,7 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="bcda2578-3b01-5e64-9d53-cd32c0f927b8")}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]="0e153ece-4fc0-5134-97f0-c2315aff0031")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
@@ -83,6 +83,7 @@ export function actionGlobalOptions(args) {
         outputLimit: readRuntimeScalarString(args, "outputLimit"),
         outputBudget: readRuntimeScalarString(args, "outputBudget"),
         outputSession: readRuntimeString(args, "outputSession"),
+        outputCursor: readRuntimeString(args, "outputCursor"),
         outputFormat: outputFormat === "json" || outputFormat === "toon"
             ? outputFormat
             : undefined,
@@ -167,6 +168,7 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputBudget",
     "outputFormat",
     "outputSession",
+    "outputCursor",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
 export function normalizeMcpOptionsArrays(options, action) {
@@ -501,4 +503,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=bcda2578-3b01-5e64-9d53-cd32c0f927b8
+//# debugId=0e153ece-4fc0-5134-97f0-c2315aff0031

package/dist/sdk/runtime-primitives.d.ts

@@ -18,7 +18,7 @@ export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, type WorkspaceAuditEventOptions, type WorkspaceHistoryChange, type WorkspaceHistoryStateAgreement, type WorkspaceJsonMutation, type WorkspaceJsonMutationOptions, type WorkspaceJsonReconciliationOptions, type WorkspaceJsonRestoreOptions, type WorkspaceJsonRestoreResult, type WorkspaceJsonWriteOptions, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="78779372-1987-54d0-9ae4-775b52641a26")}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]="a678b9f8-ba36-5127-877f-96bb4acc38c5")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -20,7 +20,7 @@ export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/hi
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
 export { readHistoryEntries } from "../core/history/read.js";
-export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, mutateWorkspaceJsonWithHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
+export { appendWorkspaceAuditEvent, appendWorkspaceHistoryChange, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, mutateWorkspaceJsonWithHistory, reconcileWorkspaceJsonHistory, restoreWorkspaceJsonFromHistory, WORKSPACE_HISTORY_ID, writeWorkspaceJsonWithHistory, } from "../core/history/workspace-history.js";
 export { normalizeReplayPatchOps, replayToCanonicalItemDocument, replayToItemDocument, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 export { resolveBodyFileContent } from "../core/io/body-file.js";
 export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
@@ -81,4 +81,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=78779372-1987-54d0-9ae4-775b52641a26
+//# debugId=a678b9f8-ba36-5127-877f-96bb4acc38c5

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="7c27b516-1714-5f2b-8304-98e8372280be")}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]="a387cd7a-cb16-5082-80e1-9632ebd02480")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -31,7 +31,7 @@ import { createExtensionCommandSdk } from "./extension-command-context.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
 import { applyContextIntentProjection, attachReadOutputContracts, } from "./context-intent-contracts.js";
 import { runWithDiscoveredContextIntentContracts, } from "./context-intent-runtime.js";
-import { validateReadOutputOptions, } from "./read-output-contracts.js";
+import { normalizeReadOutputIncludeModeOptions, validateReadOutputOptions, } from "./read-output-contracts.js";
 export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
 import { normalizeActivityProjectionOptions, runActivity, } from "./query/activity.js";
 import { runAssuranceDispatch } from "./governance/assurance-action.js";
@@ -1870,6 +1870,7 @@ export function analyzeSdkActionCoverage(actions = PM_TOOL_ACTIONS) {
 async function dispatchAction(action, args, global, activeExtensions) {
     const options = optionsWithAuthor(args, action);
     validateReadOutputOptions(action, options);
+    normalizeReadOutputIncludeModeOptions(action, options);
     const ctx = {
         action,
         args,
@@ -1883,6 +1884,7 @@ async function dispatchAction(action, args, global, activeExtensions) {
     const result = handler
         ? await handler(ctx)
         : await dispatchActiveExtensionAction(action, args, options, global, activeExtensions);
+    options.resolvedOutputFormat = "json";
     return attachReadOutputContracts(action, options, result);
 }
 const actionRunnerTestHooks = {
@@ -1930,4 +1932,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=7c27b516-1714-5f2b-8304-98e8372280be
+//# debugId=a387cd7a-cb16-5082-80e1-9632ebd02480

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-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)
+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-88mo8m](../.agents/pm/issues/pm-88mo8m.toon), [pm-atnfh4](../.agents/pm/issues/pm-atnfh4.toon), [pm-xmmafu](../.agents/pm/issues/pm-xmmafu.toon), [pm-4ok4ex](../.agents/pm/tasks/pm-4ok4ex.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.
@@ -34,6 +43,14 @@ Measurements support these built-in sources:
 | `derived`         | Combine numeric measurements with deterministic arithmetic and cycle detection.                                                          |
 | `provider`        | Delegate a measurement to an explicitly supplied host/package resolver.                                                                  |
 
+`ASSURANCE_MEASUREMENT_SOURCE_KINDS` and `ASSURANCE_GATE_TRIGGERS` are the
+public SDK constants for these closed vocabularies. Runtime validation rejects
+missing arrays and unknown discriminants with `AssuranceMutationRefusalError`;
+it never persists an unrecognized source or leaks an incidental JavaScript
+property-access error. Hosts that generate forms or package schemas can obtain
+the same values from `pm contracts --command assurance --json` under
+`assurance_contracts`.
+
 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
@@ -254,15 +271,64 @@ await pm.assurance({
 });
 ```
 
-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.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk` and its focused `@unbrained/pm-cli/sdk/governance` entrypoint. 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.
+
+Hosts that want the normal action transport and its audited registry lookup can
+pass the same adapters as the third `runAssuranceAction` argument. The request
+and project path remain transport data; resolver capabilities remain explicit
+runtime authority:
+
+```ts
+await runAssuranceAction(
+  {
+    action: "run",
+    id: "repository-static-quality",
+    trigger: "ci",
+    dry_run: true,
+  },
+  { path: ".agents/pm" },
+  {
+    workspace: {
+      include_history: false,
+      providers: {
+        "repository-quality": resolveRepositoryQualityMeasurement,
+      },
+      provider_capabilities: {
+        "repository-quality": { cost_class: "high", network: false },
+      },
+    },
+  },
+);
+```
+
+This is the migration boundary for repository automation: scripts may remain
+focused process adapters, while assertion composition, provider policy,
+negative controls, lifecycle triggers, and verdicts move into ordinary
+assurance declarations. `scripts/release/gate-registry.json` records every
+gate script as migrated, provider-backed, or retained and fails unless the
+migrated/provider-backed population is the majority.
+
+`AssuranceMutationRefusalError` and `AssuranceEvaluationRefusalError` are
+exported from both `@unbrained/pm-cli/sdk` and
+`@unbrained/pm-cli/sdk/governance`, so hosts can classify expected declaration
+or evaluation refusals without parsing messages. Source-resolution refusals
+also carry the gate, assertion, measurement, source kind, field, and optional
+health/validate check, so a zero value remains distinct from an absent or
+mistyped field.
 
 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
 pm contracts --command assurance --flags-only --json
+pm contracts --command assurance --json
 ```
 
+Command-scoped contract output omits unrelated extension, governance,
+relationship, and Commander-alias catalogs unless `--full` is requested. This
+keeps the selected action schema and its assurance vocabularies complete under
+the default output budget instead of truncating the very enum a caller needs.
+
 ## Verdict Contract
 
 A gate emits one object containing:

package/docs/COMMANDS.md

@@ -4,6 +4,8 @@ This is a task-oriented command guide. For exact flags, use runtime help because
 
 Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-qd3woa](../.agents/pm/issues/pm-qd3woa.toon), [pm-ypuc39](../.agents/pm/issues/pm-ypuc39.toon), [pm-tz2ikr](../.agents/pm/issues/pm-tz2ikr.toon), the schema-migration recovery contract [pm-s79kel](../.agents/pm/issues/pm-s79kel.toon), the lossless mutation contracts [pm-x3dq0l](../.agents/pm/issues/pm-x3dq0l.toon), [pm-lppm6y](../.agents/pm/issues/pm-lppm6y.toon), and [pm-embm6t](../.agents/pm/issues/pm-embm6t.toon), and the SDK-first agent grammar tranche [pm-p316vn](../.agents/pm/issues/pm-p316vn.toon), [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon), [pm-mkinft](../.agents/pm/issues/pm-mkinft.toon), [pm-ulqu](../.agents/pm/issues/pm-ulqu.toon), [pm-qmjx](../.agents/pm/issues/pm-qmjx.toon), [pm-4bzq](../.agents/pm/features/pm-4bzq.toon), [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon), and [pm-g543](../.agents/pm/issues/pm-g543.toon).
 
+Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
+
 ```bash
 pm <command> --help
 pm <command> --help --json
@@ -21,7 +23,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
 
@@ -943,6 +967,8 @@ pm history-repair <id> --dry-run
 pm history-repair <id> --message "re-anchor legacy drift"
 pm history-repair --all --dry-run
 pm history-repair --all --message "bulk re-anchor drifted streams"
+pm history-repair --all --normalize-provenance --dry-run
+pm history-repair --all --normalize-provenance --message "normalize invalid legacy provenance"
 pm activity                         # item digest for the last 24 hours
 pm activity --raw --id <id> --limit 50
 pm activity --full --id <id> --limit 50
@@ -998,8 +1024,10 @@ For governance dashboards, `--metadata-coverage` adds a `metadata_coverage` bloc
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied. Its result reports only `literal_count`, `regex_count`, `total_count`, and whether the default replacement was selected; literal values, regex source text, and replacement text are never echoed in CLI, SDK, MCP, recovery, profile, or telemetry output. Treat regex text as sensitive input because it can contain the exact material being removed.
 `history-compact` rewrites long streams into a synthetic checkpoint baseline plus a retained tail (`--before` accepts a 1-based version or ISO timestamp), re-anchors hashes, verifies integrity, and appends an auditable `history_compact` marker when applied.
 `history-compact` bulk mode (mutually exclusive with a positional `<id>`) compacts many streams in one audited pass. Select with `--ids <a,b,c>` (an explicit list — used on its own, not combined with the scan selectors below), or a scan: `--all-over <N>` (every stream with more than N entries) and/or a lifecycle filter `--closed` (terminal items only) or `--all-streams` (every stream). `--closed` and `--all-streams` are mutually exclusive. `--min-entries <N>` (default 3) skips already-compact streams; when `history.compact_policy` is enabled and `--all-over` is omitted, the policy's `max_entries` becomes the default threshold. `--before` is single-id only and is rejected in bulk mode. Each selected stream runs the same single-item compaction; one failing stream never aborts the rest — the result reports `totals` (`streams_considered`/`selected`/`items_compacted`/`items_skipped`/`items_errored`) plus one row per stream (`compacted`/`skipped` with a `skip_reason`/`errored`), and the command exits non-zero only if any stream errored.
-`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream.
-`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per drifted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed.
+`history-repair` re-anchors a drifted history chain when `pm health`/`pm validate --check-history-drift` report stale hashes: it replays the stream, recomputes every before/after hash using the stream's detected hash epoch, repairs legacy patch ops that no longer strictly apply, reconciles the latest hash with the on-disk item, and appends an auditable `history_repair` marker. It never modifies item content and is a safe no-op on a clean stream. The result reports the before/after hash versions and whether the epoch was preserved or selected for an ambiguous broken stream, preventing old/new runtimes from alternately rewriting an otherwise consistent legacy chain.
+`history-repair --all` (mutually exclusive with `<id>`) runs the same drift scan `pm health` uses and applies the audited single-stream repair (ownership check, lock, post-repair no-drift verification, `--message` audit marker, per-stream `--force`) to every drifted stream in one pass. One failing stream never aborts the rest: the result lists one compact row per targeted stream (`repaired` / `skipped_clean` / `failed`) plus `totals`, and the command exits non-zero only if any stream failed. Add `--normalize-provenance` to include streams containing invalid boolean or single-digit provenance observations. The normalizer removes only those invalid observations and writes aggregate harness/dimension/kind counts in the audit receipt; it never echoes or retains the removed value.
+
+Every `pm health` projection exposes `findings` and `failed_because`. A finding binds one warning token to its owning check, stable code, `advisory|gate_failing` severity, and either an executable remediation or `no_safe_automatic_remediation`. Extension health also publishes `host_version_census`, which enumerates the host and every pm-cli copy resolved by loaded extensions across npm/pnpm layouts. A version mismatch makes the extension check non-clean; matching workspace-linked or deduplicated copies remain healthy.
 
 `pm health --verbose-author-events --json` includes the complete actionable unknown-author coordinate list and an explicit `samples_truncated` marker. After evidence review, `pm history-author-acknowledge --all-actionable --attributed-author <principal> --reviewer <reviewer> --reason <evidence>` records one append-only disposition for the current complete set. `--all-actionable` and repeatable `--event <item-id:line>` are mutually exclusive; reviewer, attributed author, and reason remain mandatory.
 
@@ -1161,7 +1189,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/READ_OUTPUT_CONTRACTS.md

@@ -1,17 +1,17 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), and [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), and [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon).
 
 ## Agent Quick Context
 
 Every built-in read surface uses four output dimensions: what to include, how much to return, how much the result may cost, and how to encode it. The same canonical controls work through the CLI, SDK, MCP, generated schemas, runtime contracts, and shell completions.
 
-| Dimension | CLI                             | SDK and MCP     | Meaning                                                    |
-| --------- | ------------------------------- | --------------- | ---------------------------------------------------------- |
-| Include   | `--output-include <csv>`        | `outputInclude` | Retain named fields or top-level sections.                 |
-| Amount    | `--output-limit <n\|unbounded>` | `outputLimit`   | Bound shared row collections.                              |
-| Cost      | `--output-budget <tokens>`      | `outputBudget`  | Fail closed when even the compact result cannot fit.       |
-| Encoding  | `--output-format <toon\|json>`  | `outputFormat`  | Select the CLI renderer and record the requested encoding. |
+| Dimension | CLI                              | SDK and MCP     | Meaning                                                                |
+| --------- | -------------------------------- | --------------- | ---------------------------------------------------------------------- |
+| Include   | `--output-include <csv>`         | `outputInclude` | Retain named fields or sections, or select a declared projection mode. |
+| Amount    | `--output-limit <n\|unbounded>`  | `outputLimit`   | Bound shared row collections.                                          |
+| Cost      | `--output-budget <n\|unbounded>` | `outputBudget`  | Fail closed when even the compact result cannot fit.                   |
+| Encoding  | `--output-format <toon\|json>`   | `outputFormat`  | Select the CLI renderer and record the requested encoding.             |
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
@@ -24,6 +24,39 @@ repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
 row paths, jq selector, and active TOON encoding contract.
 
+### Include Modes
+
+`--output-include` accepts two kinds of token. A **field selector** names a row
+field or section and narrows the computed result. A **projection mode** names a
+whole declared projection and is the canonical spelling of a command-local mode
+flag: `brief`, `compact`, `full`, `summary`, and `counts`, depending on the
+surface. Controls that change execution rather than projection remain separate:
+for example, `deps --collapse <none|repeated>` retains dependency-grouping
+semantics, and `health --check-only` retains refresh-suppression semantics.
+
+Mode tokens are resolved before the command computes its rows, because a mode
+selects which fields exist rather than which of the computed fields survive.
+`pm list --output-include brief` is therefore exactly `pm list --brief`, and the
+two are byte-identical apart from the `read_output` receipt that records which
+spelling was used. Modes and field selectors compose: the mode selects the
+projection, the remaining selectors narrow it.
+
+```bash
+pm list --status open --output-include brief          # same result as --brief
+pm contracts --output-include full                    # same result as --full
+pm list --status open --output-include brief,id       # brief projection, id only
+```
+
+Read `readOutputIncludeModeOptions(command)` from the SDK for the exact
+replacement modes a surface declares. Every compatibility alias also declares
+`semantics: "replacement" | "behavior_preserving"`; generators therefore do
+not have to infer obligation strength from prose. The executable migration test
+derives all 22 projection-mode replacements from this table, invokes both
+spellings in a temporary tracker, and compares their useful result after
+removing spelling receipts and volatile run metadata. A selector that matches
+neither a declared mode nor any field on any returned row is refused with the
+legal domain, rather than returning rows with every field removed.
+
 ## Cross-Call Context Sessions
 
 `--output-session <json>` / `outputSession` composes the four per-call
@@ -84,6 +117,12 @@ tracker content.
 
 Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the four shaping dimensions retain the established data projection; the one intentional envelope correction is that repeated `row_contract` metadata is now opt-in.
 
+Completeness spellings preserve their established promise. `pm list-all` and
+list-family `--no-truncate` imply an unbounded cost dimension when the caller
+does not supply `--output-budget`; they cannot silently return a budget-trimmed
+subset while claiming to return every matched row. An explicit canonical
+budget still has precedence and may request a bounded result deliberately.
+
 ```bash
 pm list-open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
@@ -92,7 +131,43 @@ pm stats --output-row-contract
 pm contracts --full --json
 ```
 
-Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
+
+When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
+
+Cursor recovery carries the opaque value once in `recovery.cursor` and declares
+the accepting `cli`, `sdk`, and `mcp` binding beside it. This avoids
+serializing the same cursor once per transport while retaining an executable,
+machine-readable binding for each surface.
+
+Budget-compacted declared row paths are independently resumable. The
+disclosure's `continuations` entries name the row path, retained/remaining/total
+counts, and an opaque cursor. `continuation_kind` distinguishes a rebased
+producer cursor, a universal output cursor, and a terminal page;
+`next_cursor` mirrors the first universal entry for ordinary one-path
+consumers. Replay the same query and budget
+with `--output-cursor <cursor>` / `outputCursor`. The cursor validates the
+command, declared row path, total, and stable row identities before slicing, so
+a mismatched or stale replay fails closed instead of skipping evidence. A
+bounded recovery therefore does not require replacing a 600-token request with
+an unbounded multi-megabyte response;
+`recovery_budget_multiplier: 1` declares that each next page retains the same
+useful-result ceiling.
+
+Assurance declares `budget_retention_policy: verdict_priority`: failing block,
+warn, and observe rows precede retired and passing rows while preserving order
+within each class. `assertions_total` remains the pre-projection denominator,
+and the `assertions` row path uses the same continuation primitive. A blocking
+verdict consequently keeps its causal evidence on the first bounded page even
+when the failing assertion was declared last.
+
+Diagnostic gates retain bounded, actionable predicates. Every metadata field
+required by the active validation profile emits a numeric count, including
+zero, so assurance expressions can distinguish a clean check from a missing
+key. Health retains at most 100 warning rows and reports `warning_count`,
+`warning_limit`, and `warnings_truncated`; `--strict-exit` defaults to summary
+projection unless `--full` is explicit, keeping the failing check identities
+and warning codes inside the ordinary budget.
 
 ## SDK and Package Usage
 
@@ -115,6 +190,7 @@ const result = await pm.list({
     spent_tokens: 0,
     seen_item_ids: [],
   },
+  // Supply outputCursor from output_budget_truncation to fetch the next row page.
 });
 ```
 
@@ -127,5 +203,6 @@ The full runtime contract reports every surface and all four dimensions. Strict
 ```bash
 pnpm contracts:check
 node scripts/run-tests.mjs test -- tests/unit/sdk/read-output-contracts.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/read-output-migration-hints.spec.ts
 node scripts/run-tests.mjs test -- tests/unit/commands/completion-command.spec.ts
 ```

package/docs/RELATIONSHIP_GRAPH.md

@@ -1,6 +1,6 @@
 # Relationship graph semantics
 
-Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), and [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon).
+Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), and [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon).
 
 ## Decision
 
@@ -251,14 +251,21 @@ terminal dangling-reference partitions. Domain adapters pass their
 company, or package-defined edges survive assembly with their registered
 semantics. `auditWorkspaceRelationshipGraph`
 consumes that assembly and emits counts-first findings for active/terminal
-missing references, retired sentinels, ordering cycles, stale lifecycle blocks,
-and sparse or isolated active nodes. Findings include stable codes, severity,
+missing references, retired sentinels, ordering cycles, exact
+scalar-versus-structured ordering contradictions, stale lifecycle blocks, and
+sparse or isolated active nodes. Findings include stable codes, severity,
 bounded deterministic samples, truncation, policy text, and safe remediation;
 the audit never invents an edge. Explicit isolate exemptions suppress policy
 findings without changing structural coverage metrics.
 
 The audit profile also exposes graph-wide resilience and delivery-lineage
-metrics. `articulation_points` and `bridge_edges` reuse the exact cut-structure
+metrics. `nodes` and `edges` remain diagnostic totals. Structural ratchets use
+`recorded_nodes`, which excludes synthesized missing/external placeholders,
+and `informative_edges`, which subtracts the union of witnessed redundant edge
+identities and structured rows proven to contradict scalar blocker precedence.
+`redundant_edges` and `ordering_contradiction_edges` remain separate debt
+censuses so repair can tighten their ceilings without weakening the
+information-bearing floor. `articulation_points` and `bridge_edges` reuse the exact cut-structure
 algorithm; outcome metrics count explicit `Milestone` titles beginning with
 `Outcome milestone:` and follow only hierarchy or `implements` edges toward
 them. Active and terminal populations are reported separately, with integer
@@ -340,7 +347,15 @@ on terminal ones) reports raw dependency rows whose exact identity is stored
 more than once on one holder — invisible to every assembled-graph projection
 because graph construction deduplicates edges by identity, so
 `collectDuplicateDependencyRows` scans the pre-assembly item rows carried on
-the assembly. Coverage policy is type-aware: the audit profile's
+the assembly. `collectOrderingStorageContradictions` similarly scans raw rows
+before normalization: `blocked_by: target` plus a same-target source-first
+ordering dependency asserts both directions and manufactures a two-node cycle.
+The audit reports the exact holder, target, and removable dependency kind under
+`ordering_storage_contradiction` or
+`legacy_ordering_storage_contradiction`; cycle findings attach that evidence
+instead of leaving agents to re-derive the storage cause. Mutation advisories
+also identify a newly introduced contradiction before reporting its derived
+cycle. Coverage policy is type-aware: the audit profile's
 `coverage_by_type` breaks active/isolated/degree≤1 counts down per item type
 (untyped items under `(untyped)`), and `isolateExemptTypes`
 (`--exempt-isolate-type`) suppresses isolate/sparse findings for types whose