@unbrained/pm-cli 2026.8.17 → 2026.8.18

package/dist/sdk/query/complete-list.js

@@ -0,0 +1,173 @@
+/** Stable reasons a purported whole-workspace list cannot be trusted. */
+
+!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]="cc342d27-aa2d-5e84-8441-46a35c42dc00")}catch(e){}}();
+export const PM_COMPLETE_LIST_FINDING_CODES = [
+    "invalid_envelope",
+    "source_incomplete",
+    "source_unchecked",
+    "filtered_corpus",
+    "terminal_items_excluded",
+    "strict_read_unproven",
+    "page_incomplete",
+    "count_mismatch",
+    "projection_incomplete",
+    "field_omission",
+    "budget_compaction",
+    "budget_omission",
+    "session_projection",
+    "invalid_item_id",
+    "duplicate_item_id",
+];
+/** Typed fail-closed error raised when whole-corpus proof is absent. */
+export class PmCompleteListValidationError extends Error {
+    /** Structured failure and executable recovery evidence. */
+    receipt;
+    /** Construct an immutable complete-list validation failure. */
+    constructor(findings) {
+        super(`Complete-list certification failed: ${findings.map((finding) => finding.code).join(", ")}.`);
+        this.name = "PmCompleteListValidationError";
+        this.receipt = {
+            contract_version: 1,
+            contract: "complete_list",
+            findings,
+            recovery: {
+                suggested_retry: "pm list-all --full --strict-read --no-truncate --output-budget unbounded --json",
+                sdk: "await client.listAllComplete()",
+            },
+        };
+    }
+}
+/** Build the canonical all-status, full, strict, and unbounded list request. */
+export function createCompleteListOptions(options = {}) {
+    return {
+        excludeTerminal: false,
+        full: true,
+        ...(options.includeBody === undefined
+            ? {}
+            : { includeBody: options.includeBody }),
+        noTruncate: true,
+        outputBudget: "unbounded",
+        outputLimit: "unbounded",
+        strictRead: true,
+    };
+}
+/** Narrow an unknown envelope fragment to a non-array object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Append one finding only when its invariant failed. */
+function addFinding(findings, condition, code, message) {
+    if (condition)
+        findings.push({ code, message });
+}
+/** Append source-scan and filter-scope findings for a list envelope. */
+function inspectSourceScope(candidate, findings) {
+    const completeness = isRecord(candidate.completeness)
+        ? candidate.completeness
+        : {};
+    addFinding(findings, completeness.status === "partial", "source_incomplete", "The source scan reported unreadable tracker artifacts.");
+    addFinding(findings, completeness.status !== "complete" && completeness.status !== "partial", "source_unchecked", "The source scan did not prove completeness.");
+    const filters = isRecord(candidate.filters) ? candidate.filters : {};
+    const runtimeFilters = isRecord(filters.runtime_filters)
+        ? filters.runtime_filters
+        : {};
+    const filterEchoKeys = new Set([
+        "exclude_terminal",
+        "include_body",
+        "no_truncate",
+        "runtime_filters",
+        "status",
+        "strict_read",
+    ]);
+    addFinding(findings, filters.status !== "all" ||
+        Object.keys(runtimeFilters).length > 0 ||
+        Object.keys(filters).some((key) => !filterEchoKeys.has(key)), "filtered_corpus", "The list did not explicitly select every lifecycle status.");
+    addFinding(findings, filters.exclude_terminal === true, "terminal_items_excluded", "Terminal lifecycle states were explicitly excluded.");
+    addFinding(findings, filters.strict_read !== true, "strict_read_unproven", "The result does not echo strict source-read enforcement.");
+    return filters;
+}
+/** Append pagination, count, projection, and field-omission findings. */
+function inspectEnvelopeShape(candidate, filters, findings) {
+    addFinding(findings, candidate.has_more !== false ||
+        candidate.next_cursor !== null ||
+        candidate.truncated !== false ||
+        candidate.applied_limit !== undefined ||
+        filters.no_truncate !== true, "page_incomplete", "Pagination or a row ceiling may have withheld items.");
+    addFinding(findings, candidate.count !== candidate.items.length ||
+        candidate.total !== candidate.items.length, "count_mismatch", "Envelope counts do not equal the returned item count.");
+    const projection = isRecord(candidate.projection) ? candidate.projection : {};
+    addFinding(findings, projection.mode !== "full" || projection.fields !== null, "projection_incomplete", "The result is not the full metadata projection.");
+    const omissionReceipt = isRecord(candidate.omission_receipt)
+        ? candidate.omission_receipt
+        : undefined;
+    addFinding(findings, omissionReceipt?.has_omissions === true, "field_omission", "The omission receipt reports withheld field groups.");
+}
+/** Append universal-output and cross-call-session findings. */
+function inspectOutputScope(candidate, findings) {
+    const readOutput = isRecord(candidate.read_output)
+        ? candidate.read_output
+        : undefined;
+    addFinding(findings, readOutput?.strings_compacted === true ||
+        readOutput?.rows_compacted === true ||
+        candidate.output_budget_truncation !== undefined, "budget_compaction", "Universal output shaping compacted the result.");
+    const budgetExceeded = isRecord(candidate.output_budget_exceeded)
+        ? candidate.output_budget_exceeded
+        : undefined;
+    addFinding(findings, readOutput?.result_omitted === true ||
+        budgetExceeded?.omitted_result === true, "budget_omission", "Universal output shaping omitted the useful result.");
+    addFinding(findings, candidate.read_session !== undefined, "session_projection", "A cross-call read session can suppress previously served facts.");
+}
+/** Append row-identity findings that prevent exact set reasoning. */
+function inspectItemIds(items, findings) {
+    const ids = items.map((item) => isRecord(item) && typeof item.id === "string" ? item.id.trim() : "");
+    addFinding(findings, ids.some((id) => id.length === 0), "invalid_item_id", "Every full item row must carry a non-empty string id.");
+    addFinding(findings, new Set(ids).size !== ids.length, "duplicate_item_id", "Every item id must occur exactly once.");
+}
+/** Inspect an unknown result and report every missing whole-corpus invariant. */
+export function inspectCompleteListResult(candidate) {
+    if (!isRecord(candidate) || !Array.isArray(candidate.items)) {
+        return {
+            ok: false,
+            findings: [
+                {
+                    code: PM_COMPLETE_LIST_FINDING_CODES[0],
+                    message: "The result must be an object with an items array.",
+                },
+            ],
+        };
+    }
+    const envelope = candidate;
+    const findings = [];
+    const filters = inspectSourceScope(envelope, findings);
+    inspectEnvelopeShape(envelope, filters, findings);
+    inspectOutputScope(envelope, findings);
+    inspectItemIds(envelope.items, findings);
+    return { ok: findings.length === 0, findings };
+}
+/** Certify a result as the whole tracker corpus or throw a typed recovery error. */
+export function certifyCompleteListResult(candidate) {
+    const inspection = inspectCompleteListResult(candidate);
+    if (!inspection.ok) {
+        throw new PmCompleteListValidationError(inspection.findings);
+    }
+    const result = candidate;
+    return {
+        ...result,
+        complete_list: {
+            contract_version: 1,
+            item_count: result.items.length,
+            unique_item_id_count: new Set(result.items.map((item) => item.id)).size,
+            terminal_items_included: true,
+            source_complete: true,
+            full_projection: true,
+            no_omissions: true,
+            unbounded: true,
+        },
+    };
+}
+/** Assert whole-corpus completeness while narrowing the candidate type in place. */
+export function assertCompleteListResult(candidate) {
+    certifyCompleteListResult(candidate);
+}
+//# sourceMappingURL=complete-list.js.map
+//# debugId=cc342d27-aa2d-5e84-8441-46a35c42dc00

package/dist/sdk/query/list.js

@@ -4,7 +4,7 @@
  * Implements the pm list 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]="ec0c4c57-e3c2-54b3-bcf4-b4ab3b1d964e")}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]="41f54a9b-b7ba-52c1-bd84-76aa57021827")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
@@ -1106,6 +1106,9 @@ function buildVerboseListFilters(params) {
     if (noTruncate) {
         filters.no_truncate = true;
     }
+    if (options.strictRead === true) {
+        filters.strict_read = true;
+    }
     if (treeEnabled) {
         filters.tree = true;
         if (treeDepth !== undefined) {
@@ -1240,4 +1243,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=ec0c4c57-e3c2-54b3-bcf4-b4ab3b1d964e
+//# debugId=41f54a9b-b7ba-52c1-bd84-76aa57021827

package/dist/sdk/query.d.ts

@@ -4,6 +4,7 @@
  * Provides focused read, search, pagination, and context-ranking primitives.
  */
 export * from "./query/list.js";
+export * from "./query/complete-list.js";
 export * from "./query/search.js";
 export { runActivity, type ActivityCommandOptions, type ActivityEntry, type ActivityResult, type CompactActivityEntry, } from "./query/activity.js";
 export * from "./query/aggregate.js";

package/dist/sdk/query.js

@@ -4,8 +4,9 @@
  * Provides focused read, search, pagination, and context-ranking primitives.
  */
 
-!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]="5e04dc9d-8e2d-5ef2-bf8b-6b18bd87c3bc")}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]="036baf5a-3ba9-55ea-a11b-d9e94a848b92")}catch(e){}}();
 export * from "./query/list.js";
+export * from "./query/complete-list.js";
 export * from "./query/search.js";
 export { runActivity, } from "./query/activity.js";
 export * from "./query/aggregate.js";
@@ -29,4 +30,4 @@ export * from "./context-usage.js";
 export * from "./workspace-memory.js";
 export * from "./duplicates.js";
 //# sourceMappingURL=query.js.map
-//# debugId=5e04dc9d-8e2d-5ef2-bf8b-6b18bd87c3bc
+//# debugId=036baf5a-3ba9-55ea-a11b-d9e94a848b92

package/dist/sdk/read-output-contracts.d.ts

@@ -5,7 +5,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-manage", "comments-audit", "assurance"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-catalog", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -226,7 +226,7 @@ export declare const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS: readonly ["--outpu
 /** Universal output contract for every built-in read surface. */
 export declare const PM_READ_OUTPUT_SURFACE_CONTRACTS: readonly PmReadOutputSurfaceContract[];
 /** Resolve a command or list/context alias to its canonical read-output surface. */
-export declare function resolveReadOutputSurface(command: string): PmReadOutputSurface | undefined;
+export declare function resolveReadOutputSurface(command: string, options?: Record<string, unknown>): PmReadOutputSurface | undefined;
 /** Reject malformed or mutation-scoped universal output controls before command execution. */
 export declare function validateReadOutputOptions(command: string, options: Record<string, unknown>): void;
 /**

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

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!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]="e9621264-0180-53cf-862f-b59640b971da")}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]="db1d54b0-ff27-51f5-a179-14556ced24eb")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -43,6 +43,7 @@ export const PM_READ_OUTPUT_SURFACES = [
     "docs",
     "stats",
     "aggregate",
+    "package-catalog",
     "package-manage",
     "comments-audit",
     "assurance",
@@ -135,6 +136,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
     docs: {},
     stats: {},
     aggregate: {},
+    "package-catalog": {},
     "package-manage": {},
     "comments-audit": {},
     assurance: {},
@@ -208,15 +210,26 @@ const SURFACE_CONTRACT_BY_COMMAND = new Map(PM_READ_OUTPUT_SURFACE_CONTRACTS.map
     contract,
 ]));
 /** Resolve a command or list/context alias to its canonical read-output surface. */
-export function resolveReadOutputSurface(command) {
+export function resolveReadOutputSurface(command, options = {}) {
     const normalizedCommand = command
         .trim()
         .toLowerCase()
         .replaceAll(/\s+/gu, " ");
-    const root = normalizedCommand === "package manage" ||
-        normalizedCommand === "package-manage"
-        ? "package-manage"
-        : normalizedCommand.split(" ")[0];
+    const packageMode = normalizedCommand === "package catalog" ||
+        normalizedCommand === "packages catalog" ||
+        normalizedCommand === "package-catalog" ||
+        ((normalizedCommand === "package" ||
+            normalizedCommand === "packages" ||
+            normalizedCommand === "extension") &&
+            (options.catalog === true ||
+                options.target === "catalog" ||
+                options.action === "catalog"));
+    const root = packageMode
+        ? "package-catalog"
+        : normalizedCommand === "package manage" ||
+            normalizedCommand === "package-manage"
+            ? "package-manage"
+            : normalizedCommand.split(" ")[0];
     const normalized = root.startsWith("list-")
         ? "list"
         : root === "ctx"
@@ -247,6 +260,20 @@ const HYBRID_READ_MUTATION_KEYS = {
     notes: ["add", "addJson", "stdin", "file", "edit", "delete"],
     files: ["add", "addGlob", "remove", "migrate", "apply", "note"],
     docs: ["add", "addGlob", "remove", "migrate", "note"],
+    "package-catalog": [
+        "activate",
+        "adopt",
+        "adoptAll",
+        "deactivate",
+        "doctor",
+        "init",
+        "install",
+        "manage",
+        "migrate",
+        "reload",
+        "scaffold",
+        "uninstall",
+    ],
 };
 function hasCanonicalReadOutputOptions(options) {
     return CANONICAL_OPTION_KEYS.some((key) => options[key] !== undefined);
@@ -290,7 +317,7 @@ const READ_OUTPUT_VALUE_VALIDATORS = [
 export function validateReadOutputOptions(command, options) {
     if (!hasCanonicalReadOutputOptions(options))
         return;
-    const normalizedCommand = resolveReadOutputSurface(command);
+    const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand) {
         throw new PmCliError(`Universal output controls apply only to read commands; ${command || "this command"} is not a read surface.`, EXIT_CODE.USAGE);
     }
@@ -471,7 +498,7 @@ function resolveEncodingValue(canonical, legacy) {
 }
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export function resolveReadOutputDimensions(command, options) {
-    const normalizedCommand = resolveReadOutputSurface(command);
+    const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand)
         return undefined;
     const contract = SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);
@@ -1058,4 +1085,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=e9621264-0180-53cf-862f-b59640b971da
+//# debugId=db1d54b0-ff27-51f5-a179-14556ced24eb

package/dist/sdk/runtime-extended-actions.js

@@ -1,5 +1,5 @@
 
-!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]="37ac2a74-f150-5b9d-96d6-d9cc441215be")}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]="0492d773-2af2-5072-8164-9f8aab536191")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { createUnknownSubcommandError } from "./agent/subcommand-recovery.js";
@@ -32,6 +32,13 @@ export function runRuntimeEvalAction(context) {
 /** Dispatch one bounded mutation-event page through the public SDK runner. */
 export function runRuntimeEventsAction(context) {
     const input = mergedInput(context);
+    const rawCursorMode = input.cursorMode;
+    if (rawCursorMode !== undefined &&
+        rawCursorMode !== "batch" &&
+        rawCursorMode !== "row") {
+        throw new PmCliError("Mutation event cursor mode must be batch or row.", EXIT_CODE.USAGE, { code: "invalid_event_cursor_mode" });
+    }
+    const cursorMode = rawCursorMode;
     return listMutationEvents({
         cwd: readRuntimeString(input, "cwd"),
         pmRoot: readRuntimeString(input, "path"),
@@ -43,6 +50,7 @@ export function runRuntimeEventsAction(context) {
             ? undefined
             : parseRuntimeInteger(input.limit, "limit"),
         full: input.full === true,
+        cursorMode,
         ...(input.provenance === undefined
             ? {}
             : { provenance: input.provenance === true }),
@@ -161,4 +169,4 @@ export function runRuntimeSchedulingAction(context) {
     return runRemind(title, input, context.global);
 }
 //# sourceMappingURL=runtime-extended-actions.js.map
-//# debugId=37ac2a74-f150-5b9d-96d6-d9cc441215be
+//# debugId=0492d773-2af2-5072-8164-9f8aab536191

package/dist/sdk/runtime.d.ts

@@ -8,6 +8,8 @@ export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import type { ItemMetadata } from "../types/index.js";
+import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
+export { PmCompleteListValidationError, assertCompleteListResult, certifyCompleteListResult, createCompleteListOptions, inspectCompleteListResult, type PmCompleteListCertificate, type PmCompleteListFailureReceipt, type PmCompleteListFinding, type PmCompleteListFindingCode, type PmCompleteListInspection, type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
 export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
 import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
 export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
@@ -138,6 +140,8 @@ export declare class PmClient {
     listAllItemMetadataLight(): Promise<ItemMetadata[]>;
     /** List items with the MCP/agent compact defaults. */
     list<Options extends ReadOptions<ListOptions> = ListOptions>(options?: Options): ReadPromise<ListResult, Options>;
+    /** Return every status and full item row only after fail-closed corpus certification. */
+    listAllComplete(options?: PmCompleteListOptions): Promise<PmCompleteListResult>;
     /** Search items with the MCP/agent compact defaults. */
     search<Options extends ReadOptions<SearchOptions> = SearchOptions>(query: string, options?: Options): ReadPromise<SearchResult, Options>;
     /** Read one item by id. */
@@ -336,7 +340,7 @@ export declare class PmClient {
     /** Reload installed package extensions using the same action as `pm package reload`. */
     packageReload(options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Read bundled package catalog metadata using the same action as `pm package catalog`. */
-    packageCatalog(options?: PackageCommandOptions): Promise<PackageCommandResult>;
+    packageCatalog<Options extends ReadOptions<PackageCommandOptions> = PackageCommandOptions>(options?: Options): ReadPromise<PackageCommandResult, Options>;
     /** Enable an installed package using the same action as `pm package activate`. */
     packageActivate(target: string, options?: PackageCommandOptions): Promise<PackageCommandResult>;
     /** Disable an installed package using the same action as `pm package deactivate`. */
@@ -350,6 +354,8 @@ export declare class PmClient {
 export declare function context<Options extends ReadOptions<ContextOptions> = ContextOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<ContextResult, Options>;
 /** List items with the MCP/agent compact defaults without constructing a reusable client. */
 export declare function list<Options extends ReadOptions<ListOptions> = ListOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<ListResult, Options>;
+/** Return every status and full item row with fail-closed corpus proof. */
+export declare function listAllComplete(options?: PmCompleteListOptions, clientOptions?: PmClientOptions): Promise<PmCompleteListResult>;
 /** Search items with the MCP/agent compact defaults without constructing a reusable client. */
 export declare function search<Options extends ReadOptions<SearchOptions> = SearchOptions>(query: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<SearchResult, Options>;
 /** Read one item by id without constructing a reusable client. */
@@ -510,7 +516,7 @@ export declare function packageDescribe(target?: string, options?: PackageComman
 /** Reload package extensions without constructing a reusable client. */
 export declare function packageReload(options?: PackageCommandOptions, clientOptions?: PmClientOptions): Promise<PackageCommandResult>;
 /** Read bundled package catalog metadata without constructing a reusable client. */
-export declare function packageCatalog(options?: PackageCommandOptions, clientOptions?: PmClientOptions): Promise<PackageCommandResult>;
+export declare function packageCatalog<Options extends ReadOptions<PackageCommandOptions> = PackageCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<PackageCommandResult, Options>;
 /** Enable a package without constructing a reusable client. */
 export declare function packageActivate(target: string, options?: PackageCommandOptions, clientOptions?: PmClientOptions): Promise<PackageCommandResult>;
 /** Disable a package without constructing a reusable client. */

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]="bedbe090-60c3-5935-a656-da4997cd80f7")}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]="48d9b905-70a1-52c3-9b9c-33624661e6eb")}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";
@@ -23,6 +23,8 @@ import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../c
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { listClientItemMetadataLight } from "./query/light-metadata.js";
+import { certifyCompleteListResult, createCompleteListOptions } from "./query/complete-list.js";
+export { PmCompleteListValidationError, assertCompleteListResult, certifyCompleteListResult, createCompleteListOptions, inspectCompleteListResult } from "./query/complete-list.js";
 import { buildWorkspaceExtensionCommandContracts, buildWorkspaceFieldContracts, } from "./workspace-contracts.js";
 import { PM_TOOL_ACTIONS } from "./cli-contracts/enum-contracts.js";
 import { clearWorkspaceContractsCache, memoizeWorkspaceExtensionRegistrations, } from "./workspace-contracts-cache.js";
@@ -181,6 +183,8 @@ export class PmClient {
     list(options = {}) {
         return this.runTyped("list", { options });
     }
+    /** Return every status and full item row only after fail-closed corpus certification. */
+    async listAllComplete(options = {}) { return certifyCompleteListResult(await this.list(createCompleteListOptions(options))); }
     /** Search items with the MCP/agent compact defaults. */
     search(query, options = {}) {
         return this.runTyped("search", { query, options });
@@ -673,9 +677,7 @@ export class PmClient {
         return this.runTyped("package-reload", { options });
     }
     /** Read bundled package catalog metadata using the same action as `pm package catalog`. */
-    packageCatalog(options = {}) {
-        return this.runTyped("package-catalog", { options });
-    }
+    packageCatalog(options = {}) { return this.runTyped("package-catalog", { options }); }
     /** Enable an installed package using the same action as `pm package activate`. */
     packageActivate(target, options = {}) {
         return this.runTyped("package-activate", { target, options });
@@ -704,6 +706,8 @@ export function context(options = {}, clientOptions = {}) {
 export function list(options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).list(options);
 }
+/** Return every status and full item row with fail-closed corpus proof. */
+export function listAllComplete(options = {}, clientOptions = {}) { return new PmClient(clientOptions).listAllComplete(options); }
 /** Search items with the MCP/agent compact defaults without constructing a reusable client. */
 export function search(query, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).search(query, options);
@@ -997,9 +1001,7 @@ export function packageReload(options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).packageReload(options);
 }
 /** Read bundled package catalog metadata without constructing a reusable client. */
-export function packageCatalog(options = {}, clientOptions = {}) {
-    return new PmClient(clientOptions).packageCatalog(options);
-}
+export function packageCatalog(options = {}, clientOptions = {}) { return new PmClient(clientOptions).packageCatalog(options); }
 /** Enable a package without constructing a reusable client. */
 export function packageActivate(target, options = {}, clientOptions = {}) {
     return new PmClient(clientOptions).packageActivate(target, options);
@@ -1338,6 +1340,7 @@ async function runMcpListAction(ctx) {
     const listOptions = applyContextIntentProjection("list", ctx.options);
     if (listOptions.compact === undefined &&
         listOptions.brief === undefined &&
+        listOptions.full === undefined &&
         listOptions.fields === undefined &&
         listOptions.includeBody === undefined) {
         listOptions.compact = true;
@@ -1933,4 +1936,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=bedbe090-60c3-5935-a656-da4997cd80f7
+//# debugId=48d9b905-70a1-52c3-9b9c-33624661e6eb

package/dist/types.d.ts

@@ -1078,6 +1078,11 @@ export interface PmSettings {
     output: {
         default_format: "toon" | "json";
     };
+    /** Agent and human interaction preferences that do not change command semantics. */
+    ux?: {
+        /** Emit one stderr migration hint when a deprecated command alias is invoked. */
+        deprecation_hints?: boolean;
+    };
     /** Value that configures or reports history for this contract. */
     history: {
         missing_stream: "auto_create" | "strict_error";

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="4e2028b3-6718-509a-b687-d1df58962387")}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]="f6ab5bae-53b3-5feb-b89f-46e64afe7058")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=4e2028b3-6718-509a-b687-d1df58962387
+//# debugId=f6ab5bae-53b3-5feb-b89f-46e64afe7058

package/docs/AGENT_GUIDE.md

@@ -9,8 +9,8 @@ Run this before heavy work:
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm init --agent-guidance status
 pm install guide-shell --project
 pm guide workflows
@@ -28,8 +28,8 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 ```bash
 pm context --limit 10
 pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 2. **Create only when necessary**
@@ -115,13 +115,13 @@ pm release <item-id>
 | Require every query token            | `pm search "<keywords>" --match-mode and` (hard-filter; `exact` = contiguous phrase; default `or` adds an all-terms ranking bonus)                         |
 | Just the match count                 | `pm search "<keywords>" --count` (no hit rows; `count`/`total` carry the matched total)                                                                    |
 | Per-query score threshold            | `pm search "<keywords>" --min-score 5` (overrides settings `search.score_threshold` for this query)                                                        |
-| Every matched row (no cap)           | `pm list-all --no-truncate --brief` (alias `--all`; `result.total` reports the full count when a `--limit`/`--offset` truncates)                           |
-| Item bodies in bulk (one call)       | `pm list-open --json --include-body` (avoids one `pm get` per item)                                                                                        |
+| Every matched row (no cap)           | `pm list --all --no-truncate --brief` (`result.total` reports the full count when a `--limit`/`--offset` truncates)                                        |
+| Item bodies in bulk (one call)       | `pm list --status open --json --include-body` (avoids one `pm get` per item)                                                                               |
 | Open work only                       | `pm search "<keywords>" --status open` (drops closed-history noise; did-you-mean on typos)                                                                 |
 | Scope search like list               | `pm search "<keywords>" --type Task --assignee <name> --parent <id>` (full `pm list` filter parity)                                                        |
-| Items changed since last window      | `pm list-all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work)                                                                      |
-| Open items changed today             | `pm list-open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`)                                                       |
-| Items changed recently               | `pm list-all --recent --brief` (last seven days; mutually exclusive with `--updated-after`)                                                                |
+| Items changed since last window      | `pm list --all --updated-after <prev-run-ISO> --brief` (relative `-2h`/`-7d` also work)                                                                    |
+| Open items changed today             | `pm list --status open --today --brief` (local-midnight shorthand; mutually exclusive with `--updated-after`)                                              |
+| Items changed recently               | `pm list --all --recent --brief` (last seven days; mutually exclusive with `--updated-after`)                                                              |
 | Single item                          | `pm get <id>`                                                                                                                                              |
 | Full machine payload                 | `pm get <id> --full --json`                                                                                                                                |
 | Command flags                        | `pm <command> --help --json`                                                                                                                               |
@@ -171,6 +171,22 @@ Use the canonical [guide topic map](README.md#guide-topic-map) when local in-CLI
 - Use `--force` only for explicit override paths.
 - Release when pausing, handing off, or after close.
 
+## Reviewed Delivery Closeout
+
+Treat PM evidence, item closure, and the generated changelog as part of the
+reviewed change. Add all evidence known before merge to the active branch,
+close and release the item there, regenerate `CHANGELOG.md`, and include those
+artifacts in the same pull request.
+
+If evidence depends on the merge commit SHA or a post-merge hosted result, use
+a normal `main`-based follow-up pull request for the repository mutation. Never
+push tracker-only or changelog-only closeout directly to `main`: that direct
+commit becomes the release candidate but has no reviewed analyzer provenance,
+so `Release analyzer readiness (main)` must refuse it. Record external
+post-merge observations on GitHub without changing repository state when no
+tracked closeout update is required. See [Releasing](RELEASING.md#reviewed-delivery-closeout)
+for the release contract.
+
 ## Documentation Rules for Agents
 
 - Keep [README](../README.md) short.