@unbrained/pm-cli 2026.8.17 → 2026.8.19

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

@@ -5,7 +5,7 @@
  * 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]="0c69ff43-7bbc-5128-9533-bbf15365126b")}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]="810d42b5-98f4-57a7-bdd9-2dfa1b2b1c03")}catch(e){}}();
 const BUDGET_METADATA_ROOT_KEYS = new Set([
     "applied_bound",
     "completeness",
@@ -29,31 +29,43 @@ function isRecord(value) {
 function valueAtPath(result, rowPath) {
     let value = result;
     for (const segment of rowPath.split(".")) {
-        if (!isRecord(value))
-            return undefined;
-        value = value[segment];
+        if (Array.isArray(value)) {
+            if (!/^\d+$/u.test(segment))
+                return undefined;
+            value = value[Number(segment)];
+        }
+        else {
+            if (!isRecord(value))
+                return undefined;
+            value = value[segment];
+        }
     }
     return value;
 }
 /** Clone the owners along one row path and replace only its terminal value. */
 function replaceValueAtPath(result, rowPath, replacement) {
     const segments = rowPath.split(".");
-    const root = { ...result };
-    let source = result;
-    let target = root;
-    for (const segment of segments.slice(0, -1)) {
-        const sourceChild = source[segment];
-        const targetChild = { ...sourceChild };
-        target[segment] = targetChild;
-        source = sourceChild;
-        target = targetChild;
-    }
-    target[segments.at(-1)] = replacement;
-    return root;
+    const replace = (value, offset) => {
+        if (offset === segments.length)
+            return replacement;
+        const segment = segments[offset];
+        if (Array.isArray(value)) {
+            const index = Number(segment);
+            const cloned = [...value];
+            cloned[index] = replace(value[index], offset + 1);
+            return cloned;
+        }
+        const record = value;
+        return {
+            ...record,
+            [segment]: replace(record[segment], offset + 1),
+        };
+    };
+    return replace(result, 0);
 }
 /** 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);
+    const collection = readOutputContinuationRowCollections(result).find((entry) => entry.path === rowPath);
     if (!collection)
         return result;
     const replacement = Array.isArray(collection.value)
@@ -71,6 +83,14 @@ export function readOutputRowPaths(result) {
         .filter(([, value]) => Array.isArray(value))
         .map(([key]) => key);
 }
+/** Resolve collections that may be resumed independently from primary result rows. */
+export function readOutputContinuationRowPaths(result) {
+    const contract = result.row_contract;
+    if (isRecord(contract) && Array.isArray(contract.continuation_row_keys)) {
+        return contract.continuation_row_keys.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    }
+    return readOutputRowPaths(result);
+}
 /** Resolve every declared row path that currently contains iterable rows. */
 export function readOutputRowCollections(result) {
     return readOutputRowPaths(result).flatMap((rowPath) => {
@@ -80,6 +100,15 @@ export function readOutputRowCollections(result) {
             : [];
     });
 }
+/** Resolve every declared continuation path that currently contains iterable rows. */
+export function readOutputContinuationRowCollections(result) {
+    return readOutputContinuationRowPaths(result).flatMap((rowPath) => {
+        const value = valueAtPath(result, rowPath);
+        return Array.isArray(value) || isRecord(value)
+            ? [{ path: rowPath, value }]
+            : [];
+    });
+}
 /**
  * Discover every collection the token-budget degradation ladder may reduce.
  *
@@ -155,4 +184,4 @@ export function boundReadOutputRows(result, amount) {
     return { result: projected, truncated };
 }
 //# sourceMappingURL=read-output-rows.js.map
-//# debugId=0c69ff43-7bbc-5128-9533-bbf15365126b
+//# debugId=810d42b5-98f4-57a7-bdd9-2dfa1b2b1c03

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]="95764dd9-1b0d-5732-9f10-b13b334ce27d")}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;
@@ -1346,13 +1349,14 @@ async function runMcpListAction(ctx) {
     return withQuerySummary((await runList(readString(ctx.args, "status") ?? readString(listOptions, "status"), listOptions, ctx.global)), listOptions);
 }
 async function runMcpSearchAction(ctx) {
-    const searchOptions = applyContextIntentProjection("search", ctx.options);
+    const query = readRequiredString(ctx.args, "query");
+    const searchOptions = applyContextIntentProjection("search", ctx.options, [query]);
     if (searchOptions.compact === undefined &&
         searchOptions.full === undefined &&
         searchOptions.fields === undefined) {
         searchOptions.compact = true;
     }
-    return withQuerySummary((await runSearch(readRequiredString(ctx.args, "query"), searchOptions, ctx.global)), searchOptions);
+    return withQuerySummary((await runSearch(query, searchOptions, ctx.global)), searchOptions);
 }
 async function runMcpCreateAction(ctx) {
     const { changedFields, idOnly, runnerOptions } = withMutationCompaction(ctx.args, ctx.options);
@@ -1780,7 +1784,10 @@ const SDK_ACTION_HANDLERS = {
     event: runRuntimeSchedulingAction,
     remind: runRuntimeSchedulingAction,
     list: runMcpListAction,
-    get: (ctx) => runGet(requireMcpItemId(ctx), ctx.global, applyContextIntentProjection("get", ctx.options)),
+    get: (ctx) => {
+        const id = requireMcpItemId(ctx);
+        return runGet(id, ctx.global, applyContextIntentProjection("get", ctx.options, [id]));
+    },
     search: runMcpSearchAction,
     duplicates: (ctx) => {
         const status = typeof ctx.options.status === "string"
@@ -1933,4 +1940,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=bedbe090-60c3-5935-a656-da4997cd80f7
+//# debugId=95764dd9-1b0d-5732-9f10-b13b334ce27d

package/dist/sdk/workspace-snapshot.d.ts

@@ -1,5 +1,7 @@
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export declare const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export declare const WORKSPACE_SNAPSHOT_ACTIONS: readonly ["create", "list", "inspect", "restore", "delete"];
 /** Filesystem operations required by atomic snapshot publish and restore swaps. */
 export interface WorkspaceSnapshotAtomicOperations {
     /** Rename one filesystem entry atomically. */

package/dist/sdk/workspace-snapshot.js

@@ -5,7 +5,7 @@
  * 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]="36aacc71-c5f5-56f1-85f4-28b2be5b02e2")}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]="2580e043-8675-5070-b57e-30cae333228c")}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";
@@ -18,6 +18,14 @@ import { PmCliError } from "../core/shared/errors.js";
 import { withHostEnvironmentBoundary } from "./environment/host-environment-errors.js";
 /** Current content-addressed workspace snapshot manifest schema identifier. */
 export const SNAPSHOT_SCHEMA = "https://schema.unbrained.dev/pm/workspace-snapshot/v1";
+/** Workspace snapshot action tokens accepted by the SDK and CLI dispatcher. */
+export const WORKSPACE_SNAPSHOT_ACTIONS = [
+    "create",
+    "list",
+    "inspect",
+    "restore",
+    "delete",
+];
 const SNAPSHOT_RUNTIME_PATH = path.join("runtime", "workspace-snapshots");
 const EXCLUDED_ROOT_NAMES = new Set([
     "checkpoints",
@@ -603,4 +611,4 @@ export async function deleteWorkspaceSnapshot(pmRoot, target) {
     return { deleted: "object", target };
 }
 //# sourceMappingURL=workspace-snapshot.js.map
-//# debugId=36aacc71-c5f5-56f1-85f4-28b2be5b02e2
+//# debugId=2580e043-8675-5070-b57e-30cae333228c

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.

package/docs/CLI_GRAMMAR.md

@@ -0,0 +1,106 @@
+# Noun–Verb CLI Grammar and Compatibility Policy
+
+Tracked by [pm-pbyu](../.agents/pm/decisions/pm-pbyu.toon), implemented through [pm-0z7n](../.agents/pm/features/pm-0z7n.toon), [pm-pfqi](../.agents/pm/tasks/pm-pfqi.toon), [pm-yy8rmx](../.agents/pm/tasks/pm-yy8rmx.toon), and [pm-wt43zj](../.agents/pm/tasks/pm-wt43zj.toon).
+
+## Agent Quick Context
+
+Use the canonical noun-first form when generating commands. Existing spellings remain executable, but deprecated compatibility aliases are absent from default help and completion discovery and emit one migration hint on stderr. Machine clients can read alias lifecycle and replacement tokens from `pm contracts --full --json`.
+
+The first completed consolidation is the list family:
+
+```bash
+pm list                         # active lifecycle rows
+pm list --status open          # one lifecycle class
+pm list --status open,blocked  # several classes
+pm list --status blocked       # status- or dependency-blocked semantics
+pm list --all                  # every lifecycle status
+```
+
+`list-all`, `list-draft`, `list-open`, `list-in-progress`, `list-blocked`, `list-closed`, and `list-canceled` preserve command results and stdout behavior. Their documented migration hint may add one stderr line.
+
+## Status
+
+Accepted. The grammar contract, destination census, and compatibility policy are executable SDK data and mandatory static gates.
+
+## Context
+
+pm grew by adding one top-level spelling per feature. That made help, completions, contracts, documentation, and agent routing grow linearly even when several commands represented the same concept. The list family alone repeated almost the same help surface eight times. A universal project-management tool needs extensible behavior without requiring every agent to memorize an ever-growing flat vocabulary.
+
+The governing product principle is `project management = context management`: command discovery must route an agent to the smallest authoritative context, while compatibility must preserve scripts and historical instructions.
+
+## Decision Drivers
+
+- Preserve every published invocation and its stdout behavior.
+- Keep frequent operations concise without making aliases the discovery model.
+- Make domain ownership explicit enough to generate routing, help, completions, SDK contracts, MCP projections, and documentation.
+- Prevent surface regrowth with a fail-closed, bidirectional contract gate.
+- Let packages add domain behavior without consuming the core noun budget.
+- Make migration guidance suppressible for automation while keeping canonical replacements machine-readable.
+
+## Alternatives Considered
+
+### Flat surface status quo
+
+Rejected. Each feature adds another root spelling and duplicates contract/help context. A byte-count snapshot records growth but does not decide whether the new command belongs in the architecture.
+
+### Pure git-style subcommands
+
+Rejected as an exclusive rule. Noun-first paths are canonical, but forcing high-frequency operations such as `create`, `get`, `update`, `claim`, and `close` to pay an extra token on every invocation would regress the agent hot path. Named permanent aliases may remain visible and are distinguished from deprecated compatibility shims in contract data.
+
+### BusyBox-style multi-binary surface
+
+Rejected. Separate binaries multiply distribution, signing, package resolution, documentation, and shell-discovery surfaces without improving domain routing.
+
+## Decision
+
+1. The core routing vocabulary has twelve nouns: `item`, `list`, `context`, `search`, `graph`, `history`, `workspace`, `package`, `ops`, `plan`, `contracts`, and `help`.
+2. Canonical forms are noun-first. Verbs and facets are subcommands; projections and predicates are flags.
+3. Shared semantics use a shared verb vocabulary. Noun-specific verbs require an explicit checked-in disposition.
+4. Scope precedes its operation: for example, `workspace snapshot create`, not `workspace create snapshot`.
+5. Package-owned commands are declared as such and do not silently expand the core noun set.
+6. Published spellings are not removed. Deprecated spellings are hidden aliases with a canonical token sequence, PM owner, lifecycle, and one stderr migration hint.
+7. Permanent hot-path aliases and deprecated aliases are different contract states. Permanent aliases are ergonomic API; deprecated aliases are compatibility state.
+8. Every live command has exactly one destination row. A row may name its target noun, a tracked consolidation owner, a package owner, or a reasoned keep-as-is exception.
+9. The census is bidirectional: missing live rows and stale checked-in rows both fail CI.
+10. Default-visible top-level growth is ceilinged. Lowering the ceiling is always valid; raising it requires a tracked noun-placement decision rather than regenerating a baseline.
+
+## SDK Contract
+
+Package authors and embedded clients use the public exports:
+
+```ts
+import {
+  PM_CLI_GRAMMAR_CONTRACT,
+  PM_COMMAND_ALIAS_CONTRACTS,
+  PM_COMMAND_DESTINATION_CONTRACTS,
+  resolvePmCommandAlias,
+  verifyPmCliGrammar,
+} from "@unbrained/pm-cli/sdk";
+```
+
+`PM_COMMAND_ALIAS_CONTRACTS` carries `alias`, `canonical`, `canonical_argv`, `lifecycle`, `hidden`, `registration`, and `owner`. `verifyPmCliGrammar` returns deterministic findings with an offending spelling and nearest conforming target.
+
+Runtime contracts expose the compact noun/verb policy in summary output and include the exhaustive destination census in full output. Deprecated aliases remain queryable but are excluded from the default command-summary denominator.
+
+## Compatibility and Migration Hints
+
+Hints go to stderr exactly once per deprecated-alias invocation and never alter stdout. Disable them for a project when an automation intentionally retains old spellings:
+
+```bash
+pm config project set ux_deprecation_hints false
+```
+
+This setting changes presentation only. It does not disable aliases or change command results. The uniform machine result-envelope receipt is intentionally deferred to its separately tracked cross-command contract so this implementation does not create a list-only shape.
+
+## Enforcement
+
+`pnpm quality:command-grammar` builds the SDK, reads the live runtime command contracts, and compares them with the checked-in destination and alias tables. Package-owned destination rows are conditional because installed packages vary by workspace; every activated package command still requires a declared row, while an inactive package does not make its row stale. The gate also proves parity between discoverable SDK actions, the MCP `pm_run` action enum, and narrow MCP tools. The same gate runs inside `quality:static`, alongside contract drift checks. Its negative controls prove that unknown commands, stale core rows, broken alias targets, MCP drift, and surface-ceiling growth fail upward.
+
+## Consequences
+
+- Agents discover one list command instead of eight repeated help pages.
+- Existing scripts keep working and receive an actionable replacement.
+- CLI, SDK, completion, and contract consumers share one alias table.
+- New commands require an explicit architectural home and PM owner.
+- The compatibility table is long-lived public API and must be reviewed like any other SDK contract.
+- Consolidation proceeds incrementally: current legacy commands may remain only with a named disposition until their owning PM item lands.