@unbrained/pm-cli 2026.8.16 → 2026.8.18

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/sdk/schema.d.ts

@@ -500,6 +500,7 @@ export declare function formatSchemaApplyPresetHuman(result: SchemaApplyPresetRe
 export declare function formatSchemaInferTypesHuman(result: SchemaAddTypeInferResult): string;
 /** Re-export so register-mutation can surface the hint in usage examples without importing the core module directly. */
 export { buildInvalidTypeHint };
+export type { RuntimeFieldDefinition, RuntimeFieldValueSchema, } from "../core/schema/fields-file.js";
 /** Public contract for test only schema command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlySchemaCommand: {
     workflowSlotsReferencing: typeof workflowSlotsReferencing;

package/dist/sdk/schema.js

@@ -4,7 +4,7 @@
  * Owns typed schema customization primitives shared by SDK, CLI, and MCP consumers.
  */
 
-!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]="1a035e10-b8fe-52cd-a9c7-0762dd0ab160")}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]="2ab8a5a9-dbea-526f-a541-b7ca2b106ac5")}catch(e){}}();
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -1365,4 +1365,4 @@ export const _testOnlySchemaCommand = {
     workflowSlotsReferencing,
 };
 //# sourceMappingURL=schema.js.map
-//# debugId=1a035e10-b8fe-52cd-a9c7-0762dd0ab160
+//# debugId=2ab8a5a9-dbea-526f-a541-b7ca2b106ac5

package/dist/sdk/test/execution.d.ts

@@ -201,7 +201,9 @@ declare function formatLinkedTestExecutionError(result: LinkedTestExecutionResul
 export declare function classifyLinkedTestFailure(result: Pick<LinkedTestExecutionResult, "stdout" | "stderr" | "spawnError" | "signal" | "timedOut" | "maxBufferExceeded">): LinkedTestFailureCategory;
 /** Implements count failure categories for the public runtime surface of this module. */
 export declare function countFailureCategories(runResults: TestRunResult[]): Record<LinkedTestFailureCategory, number>;
-declare function copyIntoSandboxIfPresent(sourcePath: string, targetPath: string, recursive?: boolean): Promise<void>;
+declare function copyIntoSandboxIfPresent(sourcePath: string, targetPath: string, recursive?: boolean, makeDirectory?: (targetPath: string, options: {
+    recursive: true;
+}) => Promise<unknown>): Promise<void>;
 declare function seedLinkedTestSandbox(sandboxPmPath: string, sandboxGlobalPath: string, sourceRoots: LinkedTestSandboxSourceRoots): Promise<void>;
 declare function seedLinkedTestTrackerData(sourceRoot: string, sandboxRoot: string): Promise<void>;
 declare function countLinkedTestItemFiles(pmRoot: string): Promise<number>;
@@ -242,7 +244,8 @@ interface LinkedTestSandboxCounts {
     trackerProjectItemCount: number;
     trackerGlobalItemCount: number;
 }
-declare function initializeLinkedTestSandboxes(layout: LinkedTestSandboxLayout, initialize?: (...args: Parameters<typeof runInit>) => Promise<unknown>): Promise<void>;
+declare function initializeLinkedTestSandboxes(layout: LinkedTestSandboxLayout, initialize?: (...args: Parameters<typeof runInit>) => Promise<unknown>, includeTrackerData?: boolean): Promise<void>;
+declare function linkedTestsRequireTrackerData(tests: LinkedTest[], runLevelPmContextMode: LinkedTestPmContextMode, options: RunLinkedTestsOptions | undefined): boolean;
 declare function buildLinkedTestExecutionContext(params: {
     layout: LinkedTestSandboxLayout;
     counts: LinkedTestSandboxCounts;
@@ -280,6 +283,7 @@ export declare const _testOnlyTestCommand: {
     formatLinkedTestExecutionError: typeof formatLinkedTestExecutionError;
     hasLinkedTestAssertions: typeof hasLinkedTestAssertions;
     initializeLinkedTestSandboxes: typeof initializeLinkedTestSandboxes;
+    linkedTestsRequireTrackerData: typeof linkedTestsRequireTrackerData;
     parseAddJsonEntries: typeof parseAddJsonEntries;
     parseLinkedTestTimeoutSeconds: typeof parseLinkedTestTimeoutSeconds;
     parsePmContextMode: typeof parsePmContextMode;

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="76053150-cc55-57e0-80d6-369196284cd0")}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]="4322c352-6b95-5796-94eb-5a68745d53bc")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -28,6 +28,7 @@ import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TE
 import { parseOnlyIndexValue, resolveLinkedTestRunSelection, } from "../../core/test/run-selectors.js";
 import { SCOPE_VALUES } from "../../types/index.js";
 import { diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./measurements.js";
+import { withHostEnvironmentBoundary } from "../environment/host-environment-errors.js";
 import { SOURCE_CONTEXT_ACCESS_ENV } from "../environment/source-context.js";
 const TEST_OUTPUT_MAX_BUFFER_BYTES = 20 * 1024 * 1024;
 const DEFAULT_LINKED_TEST_TIMEOUT_FORCE_KILL_DELAY_MS = 3000;
@@ -973,17 +974,24 @@ function resolveRuntimeDirectives(envSetEntries, envClearEntries, sharedHostSafe
     };
 }
 /* c8 ignore start -- sandbox copy race/path permutations are covered by filesystem integration suites */
-async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = false) {
+async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = false, makeDirectory = mkdir) {
     if (!(await pathExists(sourcePath))) {
         return;
     }
-    await mkdir(path.dirname(targetPath), { recursive: true });
     try {
-        if (recursive) {
-            await cp(sourcePath, targetPath, { recursive: true, force: true });
-            return;
-        }
-        await cp(sourcePath, targetPath, { force: true });
+        await withHostEnvironmentBoundary("seed_linked_test", async () => {
+            await makeDirectory(path.dirname(targetPath), { recursive: true });
+            if (recursive) {
+                await cp(sourcePath, targetPath, { recursive: true, force: true });
+                return;
+            }
+            await cp(sourcePath, targetPath, { force: true });
+        }, {
+            why: "Linked tests need an isolated PM context without mutating the source tracker.",
+            nextSteps: [
+                "Reclaim capacity on the filesystem that hosts the linked-test temporary directory.",
+            ],
+        });
     }
     catch (error) {
         if (typeof error === "object" &&
@@ -1257,22 +1265,38 @@ function createLinkedTestSandboxLayout(sandboxRoot) {
         trackerGlobalPmPath: path.join(sandboxRoot, "tracker", "global"),
     };
 }
-async function initializeLinkedTestSandboxes(layout, initialize = runInit) {
+async function initializeLinkedTestSandboxes(layout, initialize = runInit, includeTrackerData = true) {
     const initOptions = { defaults: true, agentGuidance: "skip" };
     await initialize(undefined, { path: layout.schemaProjectPmPath }, initOptions);
     await initialize(undefined, { path: layout.schemaGlobalPmPath }, initOptions);
+    if (!includeTrackerData) {
+        return;
+    }
     await initialize(undefined, { path: layout.trackerProjectPmPath }, initOptions);
     await initialize(undefined, { path: layout.trackerGlobalPmPath }, initOptions);
 }
-async function seedLinkedTestSandboxesFromSource(layout, sourceRoots) {
+async function seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTrackerData) {
     if (!sourceRoots) {
         return;
     }
     await seedLinkedTestSandbox(layout.schemaProjectPmPath, layout.schemaGlobalPmPath, sourceRoots);
+    if (!includeTrackerData) {
+        return;
+    }
     await seedLinkedTestSandbox(layout.trackerProjectPmPath, layout.trackerGlobalPmPath, sourceRoots);
     await seedLinkedTestTrackerData(sourceRoots.projectPmRoot, layout.trackerProjectPmPath);
     await seedLinkedTestTrackerData(sourceRoots.globalPmRoot, layout.trackerGlobalPmPath);
 }
+function linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options) {
+    return tests.some((linkedTest) => {
+        const command = linkedTest.command ?? "";
+        const isPmTrackerReadCommand = command.length > 0 && commandInvokesPmTrackerReadCommand(command);
+        const requestedPmContextMode = options?.autoPmContext === true && isPmTrackerReadCommand
+            ? "auto"
+            : resolveLinkedTestRequestedContextMode(linkedTest, runLevelPmContextMode, options?.overrideLinkedPmContext === true);
+        return (resolveLinkedTestEffectiveContextMode(requestedPmContextMode, isPmTrackerReadCommand) === "tracker");
+    });
+}
 async function countLinkedTestSandboxItems(layout, sourceRoots) {
     return {
         sourceProjectItemCount: sourceRoots
@@ -1510,9 +1534,10 @@ export async function runLinkedTests(tests, defaultTimeoutSeconds, options) {
     const progressMode = options?.progress === true ? "always" : "auto";
     const runtimeDirectives = resolveRuntimeDirectives(options?.envSet, options?.envClear, options?.sharedHostSafe);
     const sourceRoots = options?.sourceRoots;
+    const includeTrackerData = linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options);
     try {
-        await initializeLinkedTestSandboxes(layout);
-        await seedLinkedTestSandboxesFromSource(layout, sourceRoots);
+        await initializeLinkedTestSandboxes(layout, runInit, includeTrackerData);
+        await seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTrackerData);
         const counts = await countLinkedTestSandboxItems(layout, sourceRoots);
         for (let index = 0; index < tests.length; index += 1) {
             const linkedTest = tests[index];
@@ -1920,6 +1945,7 @@ export const _testOnlyTestCommand = {
     formatLinkedTestExecutionError,
     hasLinkedTestAssertions,
     initializeLinkedTestSandboxes,
+    linkedTestsRequireTrackerData,
     parseAddJsonEntries,
     parseLinkedTestTimeoutSeconds,
     parsePmContextMode,
@@ -1939,4 +1965,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=76053150-cc55-57e0-80d6-369196284cd0
+//# debugId=4322c352-6b95-5796-94eb-5a68745d53bc

package/dist/types.d.ts

@@ -32,7 +32,7 @@ export declare const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES: readonly ["allow", "wa
 /** Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts. */
 export type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];
 /** Supported values accepted by the dependency kind contract. */
-export declare const DEPENDENCY_KIND_VALUES: readonly ["blocks", "parent", "child", "parent_child", "child_of", "related", "related_to", "discovered_from", "blocked_by", "incident_from", "epic", "implements", "supersedes", "task", "verifies"];
+export declare const DEPENDENCY_KIND_VALUES: readonly ["blocks", "parent", "child", "parent_child", "child_of", "related", "related_to", "discovered_from", "blocked_by", "incident_from", "epic", "implements", "recurs_from", "supersedes", "task", "verifies"];
 /** Restricts dependency kind values accepted by command, SDK, and storage contracts. */
 export type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];
 /** Supported values accepted by the scope contract. */
@@ -266,7 +266,7 @@ export declare const PLAN_HARNESS_VALUES: readonly ["codex", "claude-code", "cur
 /** Restricts plan harness values accepted by command, SDK, and storage contracts. */
 export type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];
 /** Supported values accepted by the plan step link kind contract. */
-export declare const PLAN_STEP_LINK_KIND_VALUES: readonly ["related", "blocks", "blocked_by", "depends_on", "discovered_from", "implements", "verifies", "supersedes"];
+export declare const PLAN_STEP_LINK_KIND_VALUES: readonly ["related", "blocks", "blocked_by", "depends_on", "discovered_from", "implements", "recurs_from", "verifies", "supersedes"];
 /** Restricts plan step link kind values accepted by command, SDK, and storage contracts. */
 export type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];
 /** Documents the plan step link payload exchanged by command, SDK, and package integrations. */
@@ -437,6 +437,31 @@ export interface RuntimeStatusDefinition {
     /** Value that configures or reports order for this contract. */
     order?: number;
 }
+/** Declarative JSON-value constraints enforced before custom-field persistence. */
+export interface RuntimeFieldValueSchema {
+    /** Optional JSON value type constraint. */
+    type?: "string" | "number" | "boolean" | "array" | "object";
+    /** Exact JSON value required by this schema branch. */
+    const?: StructuredJsonValue;
+    /** Complete allowed JSON value set. */
+    enum?: StructuredJsonValue[];
+    /** Minimum accepted string length. */
+    min_length?: number;
+    /** Minimum accepted array length. */
+    min_items?: number;
+    /** Optional semantic string format. */
+    format?: "date-time";
+    /** Object-property schemas keyed by the persisted property name. */
+    properties?: Record<string, RuntimeFieldValueSchema>;
+    /** Object properties that must be present. */
+    required?: string[];
+    /** Whether properties absent from `properties` are accepted. */
+    additional_properties?: boolean;
+    /** Schema applied to every array element. */
+    items?: RuntimeFieldValueSchema;
+    /** Alternative schemas of which exactly one must match. */
+    one_of?: RuntimeFieldValueSchema[];
+}
 /** Documents the runtime field definition payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeFieldDefinition {
     /** Value that configures or reports key for this contract. */
@@ -467,6 +492,8 @@ export interface RuntimeFieldDefinition {
     required_types?: string[];
     /** Value that configures or reports allow unset for this contract. */
     allow_unset?: boolean;
+    /** Optional semantic JSON-value constraints enforced on create and update. */
+    value_schema?: RuntimeFieldValueSchema;
 }
 /** Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeWorkflowDefinition {
@@ -1051,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]="8b39bc01-0325-5dc6-8492-585c98608076")}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",
@@ -81,6 +81,7 @@ export const DEPENDENCY_KIND_VALUES = [
     "incident_from",
     "epic",
     "implements",
+    "recurs_from",
     "supersedes",
     "task",
     "verifies",
@@ -217,6 +218,7 @@ export const PLAN_STEP_LINK_KIND_VALUES = [
     "depends_on",
     "discovered_from",
     "implements",
+    "recurs_from",
     "verifies",
     "supersedes",
 ];
@@ -241,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=8b39bc01-0325-5dc6-8492-585c98608076
+//# 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.

package/docs/COMMANDS.md

@@ -141,8 +141,8 @@ pm search "calendar reminder validation" --limit 10
 pm get pm-a1b2                          # read one item; add --fields/--depth for lower-token projections
 pm get pm-a1b2 --tree --tree-depth 2    # item plus its descendant subtree
 pm get pm-a1b2 --at 7                   # verified, mutation-free historical version
-pm list-open --type Task --priority 1 --limit 20
-pm list-in-progress --limit 20
+pm list --status open --type Task --priority 1 --limit 20
+pm list --status in_progress --limit 20
 pm aggregate --group-by parent,type --status open
 pm aggregate --group-by parent,type --completion --include-unparented
 pm duplicates --status all --threshold 0.8
@@ -173,7 +173,7 @@ Each aggregate row carries an explicit `group_label`: a blank/null group value (
 `--sort` accepts `priority|deadline|updated_at|created_at|title|parent`, plus the convenience aliases `updated` (→ `updated_at`) and `created` (→ `created_at`):
 
 ```bash
-pm list-all --sort updated --order desc
+pm list --all --sort updated --order desc
 ```
 
 ### Incremental "what changed since" filters
@@ -182,16 +182,16 @@ Every `list*` command accepts `--updated-after`/`--updated-before`/`--created-af
 
 ```bash
 # Items touched since my last context window (feed back the previous run's `now`)
-pm list-all --updated-after 2026-06-04T15:18:32Z --brief
+pm list --all --updated-after 2026-06-04T15:18:32Z --brief
 
 # Relative offsets are SIGNED: -2h/-7d reach into the past, +1d into the future.
 # Units are h/d/w/m (m = months — there is no minutes unit).
-pm list-open --updated-after=-2h --brief
-pm list-all --created-after=-7d --status open
+pm list --status open --updated-after=-2h --brief
+pm list --status open --created-after=-7d
 
-# Common list windows avoid date math (`list-open` keeps the view open-only).
-pm list-open --today --brief
-pm list-all --recent --brief
+# Common list windows avoid date math (`pm list --status open` keeps the view open-only).
+pm list --status open --today --brief
+pm list --all --recent --brief
 
 # Search scoped to open work only (drops closed-history noise); statuses accept
 # all (no lifecycle restriction), open/closed/canceled aliases, or configured
@@ -293,12 +293,12 @@ pm eval --fail-under 0.6 --json      # CI gate: exit non-zero when aggregate nDC
 
 ### Full results, totals, and bodies
 
-`pm list*` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` (alias `--all`) to force the entire matched set and override any `--limit` in one call — the canonical "give me everything" flag for large-corpus audits:
+`pm list` returns every matched row when neither `--limit` nor `--offset` is set. Every JSON/TOON result has the same pagination envelope: `total` is the pre-pagination match count, `has_more` and `truncated` are booleans, and `next_cursor` is either the continuation token or `null`. `completeness` reports whether the corpus was `complete`, `partial`, or `unchecked` (derived-index page), with unreadable item/directory counts. Use `--strict-read` when omissions must fail the command. The `filters` object omits unset values instead of emitting null placeholders, keeping long-running agent context stable and lean. Pass `--no-truncate` to force the entire matched set and override any `--limit` in one call. `--all` selects every lifecycle status; combine the flags for an unbounded all-status audit:
 
 ```bash
-pm list-all --no-truncate --brief          # every matched row, ignoring any --limit
-pm list-open --limit 20 --json             # stable total/has_more/truncated/next_cursor envelope
-pm list-all --strict-read --json           # fail if any source item cannot be read
+pm list --all --no-truncate --brief        # every matched row, ignoring any --limit
+pm list --status open --limit 20 --json    # stable total/has_more/truncated/next_cursor envelope
+pm list --all --strict-read --json         # fail if any source item cannot be read
 ```
 
 Compatibility note: older responses emitted `total` only when pagination
@@ -312,7 +312,7 @@ unconditional pre-pagination match count, branch on `has_more` or
 JSON output is compact by default (id/status/type/title) for token efficiency. To pull item bodies in bulk in a single call — instead of one `pm get` per item — add `--include-body`, which expands each row to the full field set plus `body`:
 
 ```bash
-pm list-open --json --include-body         # full fields + body for every returned row
+pm list --status open --json --include-body # full fields + body for every returned row
 ```
 
 `pm get <id> --json` returns the item's `body` **inside** the `item` object (i.e. `.item.body`), matching where `list --include-body` places it and the long-form `description`/`acceptance_criteria` fields — so a single read exposes every field at a consistent path. Body is included at the default `standard` depth and above; `--depth brief` omits it.
@@ -322,10 +322,10 @@ pm list-open --json --include-body         # full fields + body for every return
 `pm list*` accepts `--format <csv|table|json|ndjson|toon>` to choose how rows render. `csv` and `table` are **human export** modes — pipe them into a spreadsheet or read them directly in a terminal — while `json`/`toon` override the machine output format the same way the global `--json` flag does. `ndjson` writes each projected item as one self-contained JSON object per line, with no wrapper or trailing summary. The rendered fields follow the active projection, so combine `--format` with `--fields`/`--brief`/`--compact` to control exactly what appears:
 
 ```bash
-pm list-open --format table                      # aligned, monospace-friendly columns
-pm list-all --fields id,title,priority --format csv  # spreadsheet export with chosen columns
-pm list-open --format csv > backlog.csv          # capture for reporting
-pm list-all --brief --format ndjson | jq -c 'select(.status == "open")'
+pm list --status open --format table                 # aligned, monospace-friendly columns
+pm list --all --fields id,title,priority --format csv # spreadsheet export with chosen columns
+pm list --status open --format csv > backlog.csv     # capture for reporting
+pm list --all --brief --format ndjson | jq -c 'select(.status == "open")'
 ```
 
 CSV output is RFC 4180 compliant (values with commas, quotes, or newlines are quoted; array fields such as `tags` join with `;`). `--format csv|table|ndjson` cannot be combined with the legacy envelope-oriented `--stream` mode.
@@ -338,13 +338,13 @@ The same `list*` commands and `pm search` extend this with governance-field pres
 
 ```bash
 # Find open Tasks that still need acceptance criteria
-pm list-open --type Task --filter-ac-missing --brief
+pm list --status open --type Task --filter-ac-missing --brief
 
 # Closed items that were never given a resolution
-pm list-closed --filter-resolution-missing --json
+pm list --status closed --filter-resolution-missing --json
 
 # Open items that still need a reviewer assigned
-pm list-open --filter-reviewer-missing --brief
+pm list --status open --filter-reviewer-missing --brief
 ```
 
 ### Content-field presence filters
@@ -353,10 +353,10 @@ pm list-open --filter-reviewer-missing --brief
 
 ```bash
 # Closed items that shipped no documented learnings
-pm list-closed --no-learnings --brief
+pm list --status closed --no-learnings --brief
 
 # Open work that has linked tests but no linked files yet
-pm list-open --has-tests --no-files --json
+pm list --status open --has-tests --no-files --json
 ```
 
 ## Bulk Operations