@unbrained/pm-cli 2026.8.19 → 2026.8.20

package/dist/sdk/lifecycle/update.js

@@ -4,8 +4,9 @@
  * Implements the pm update 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]="a421c150-13a9-5334-85a4-5b3199a5d2c7")}catch(e){}}();
-import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="3ab4f16d-ce37-546e-a2f6-0495fd1967c7")}catch(e){}}();
+import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { mutateItemWithHistoryContextResolver } from "../../core/store/item-store.js";
 import { runClose } from "./close.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
 import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken, } from "./legacy-none-tokens.js";
@@ -1214,8 +1215,8 @@ function applyStatusMutation(document, context, statusInput, previousStatusNorma
         changedFields.push("closed_at", "completed_at");
         return;
     }
-    if (status !== context.statusRegistry.close_status &&
-        previousStatusNormalized === context.statusRegistry.close_status &&
+    if (!isTerminalStatus(status, context.statusRegistry) &&
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
         document.metadata.closed_at !== undefined) {
         delete document.metadata.closed_at;
         changedFields.push("closed_at");
@@ -1254,8 +1255,8 @@ function applyCloseReasonMutations(document, context, previousStatusNormalized,
         return;
     }
     if (context.options.status !== undefined &&
-        previousStatusNormalized === context.statusRegistry.close_status &&
-        document.metadata.status !== context.statusRegistry.canceled_status &&
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
+        !isTerminalStatus(document.metadata.status, context.statusRegistry) &&
         document.metadata.close_reason !== undefined) {
         delete document.metadata.close_reason;
         changedFields.push("close_reason");
@@ -1700,7 +1701,7 @@ function mutateUpdateDocument(document, context) {
     return { changedFields: actualChangedFields, warnings };
 }
 /** Implements run update for the public runtime surface of this module. */
-export async function runUpdate(id, options, global) {
+async function runUpdateWithContext(id, options, global, execution = {}) {
     options = await resolveStdinUpdateOptions(options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
     await assertUpdateTrackerInitialized(pmRoot);
@@ -1820,23 +1821,32 @@ export async function runUpdate(id, options, global) {
     let graphBeforeUpdate = fieldFlags.dep || fieldFlags.depRemove || fieldFlags.blockedBy
         ? await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema)
         : undefined;
-    const result = await mutateItem({
+    let lifecycleTransition;
+    let recurrenceHistoryContext;
+    const result = await mutateItemWithHistoryContextResolver({
         pmRoot,
         settings,
         typeToFolder: typeRegistry.type_to_folder,
         id,
-        op: options.ownershipMetadataBypass === true ||
-            options.ownershipDependencyBypass === true
-            ? "update_ownership_bypass"
-            : "update",
+        op: resolveUpdateHistoryOperation(options, execution),
         author,
         message: options.message,
+        resolveHistoryContext: () => recurrenceHistoryContext,
         force: options.force,
         bypassAssigneeConflict: options.ownershipMetadataBypass === true ||
             options.ownershipDependencyBypass === true,
         extensionFieldNames,
         skipNoop: true,
         mutate(document) {
+            lifecycleTransition = prepareRecurrenceTransition({
+                document,
+                recurrenceReason: execution.recurrenceReason,
+                requestedStatus: options.status,
+                statusRegistry,
+            });
+            recurrenceHistoryContext = lifecycleTransition
+                ? { recurrence: lifecycleTransition }
+                : undefined;
             graphBeforeUpdate = graphBeforeUpdate?.map((item) => item.id === document.metadata.id
                 ? structuredClone(document.metadata)
                 : item);
@@ -1880,8 +1890,80 @@ export async function runUpdate(id, options, global) {
             ...orderingCycleWarnings,
             ...result.warnings,
         ],
+        ...(lifecycleTransition === undefined
+            ? {}
+            : { lifecycle_transition: lifecycleTransition }),
     };
 }
+/** Resolve the immutable operation name for ordinary, bypass, and recurrence updates. */
+function resolveUpdateHistoryOperation(options, execution) {
+    if (options.ownershipMetadataBypass === true ||
+        options.ownershipDependencyBypass === true) {
+        return "update_ownership_bypass";
+    }
+    return execution.recurrenceReason === undefined ? "update" : "reopen";
+}
+/** Validate and capture a terminal-to-active recurrence while the item lock is held. */
+function prepareRecurrenceTransition(params) {
+    if (params.recurrenceReason === undefined) {
+        return undefined;
+    }
+    const fromStatus = normalizeStatusInput(params.document.metadata.status, params.statusRegistry) ?? params.document.metadata.status;
+    if (!isTerminalStatus(fromStatus, params.statusRegistry)) {
+        throw new PmCliError(`Item ${params.document.metadata.id} is already active with status ${fromStatus}; recurrence transitions require a terminal item.`, EXIT_CODE.CONFLICT, {
+            code: "item_already_active",
+            reason: "recurrence_requires_terminal_item",
+            required: "Use item reopen only for a terminal item whose work has recurred.",
+            why: "Appending a recurrence event to active work would corrupt lifecycle history.",
+            recovery: {
+                suggested_retry: `pm get ${params.document.metadata.id} --full`,
+                suggested_retry_args: ["get", params.document.metadata.id, "--full"],
+            },
+            nextSteps: [
+                `Inspect the active item with: pm get ${params.document.metadata.id} --full`,
+                `Continue the existing work with: pm update ${params.document.metadata.id} ...`,
+            ],
+        });
+    }
+    const requestedStatus = params.requestedStatus ?? params.statusRegistry.open_status;
+    const toStatus = normalizeStatusInput(requestedStatus, params.statusRegistry) ??
+        requestedStatus;
+    const metadata = toItemRecord(params.document.metadata);
+    const previousTerminal = Object.fromEntries([
+        "close_reason",
+        "resolution",
+        "expected_result",
+        "actual_result",
+        "fixed_version",
+    ].flatMap((key) => {
+        const value = metadata[key];
+        return typeof value === "string" ? [[key, value]] : [];
+    }));
+    return {
+        reason: params.recurrenceReason,
+        from_status: fromStatus,
+        to_status: toStatus,
+        previous_terminal: previousTerminal,
+    };
+}
+/** Implements run update for the public runtime surface of this module. */
+export async function runUpdate(id, options, global) {
+    return runUpdateWithContext(id, options, global);
+}
+/** Execute a recurrence transition through the exact atomic update pipeline. */
+export async function runReopenUpdate(id, options, global, recurrenceReason) {
+    const result = await runUpdateWithContext(id, options, global, {
+        recurrenceReason,
+    });
+    if (result.lifecycle_transition === undefined) {
+        throw new PmCliError(`Item ${id} did not produce the required recurrence receipt.`, EXIT_CODE.GENERIC_FAILURE, {
+            code: "reopen_receipt_missing",
+            reason: "recurrence_transition_not_recorded",
+            required: "A successful reopen must return the terminal-to-active lifecycle transition recorded in immutable history.",
+        });
+    }
+    return { ...result, lifecycle_transition: result.lifecycle_transition };
+}
 /* c8 ignore stop */
 /** Public contract for test only update command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyUpdateCommand = {
@@ -1900,4 +1982,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=a421c150-13a9-5334-85a4-5b3199a5d2c7
+//# debugId=3ab4f16d-ce37-546e-a2f6-0495fd1967c7

package/dist/sdk/query/get.d.ts

@@ -7,6 +7,7 @@ import { type GlobalOptions } from "../runtime-primitives.js";
 import { type ChildRollupContext } from "../item-children.js";
 import { type ItemScheduleContext } from "../item-schedule.js";
 import type { ItemMetadata, LinkedDoc, LinkedFile, LinkedTest } from "../../types/index.js";
+export { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
 interface ClaimHistoryContext {
     ts: string;
     author: string;
@@ -92,4 +93,3 @@ export declare function runGet(id: string, global: GlobalOptions, options?: GetO
 export declare const _testOnlyGetCommand: {
     shouldAutoIncludeGetChildren: typeof shouldAutoIncludeGetChildren;
 };
-export {};

package/dist/sdk/query/get.js

@@ -4,8 +4,8 @@
  * Implements the SDK-owned item query shared by every surface.
  */
 
-!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]="1ba3eb17-c44c-5b62-8ae0-c2506fca9c62")}catch(e){}}();
-import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+!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]="16d0a1cf-467d-5041-ab36-e2a9033a9342")}catch(e){}}();
+import { pathExists, getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { readHistoryEntries } from "../history-read.js";
 import { renderPmCommand } from "../command-line.js";
 import { recordContextUsageTouches } from "../context-usage.js";
@@ -15,7 +15,8 @@ import { getItemAt } from "../history-read.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { runList } from "./list.js";
 import { registerOutputMaterialFieldGroups } from "../output-projection.js";
-const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
+import { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
+export { GET_DEPTH_VALUES, listGetProjectionFields, } from "./projection-contracts.js";
 const AUTOMATIC_CHILD_ROLLUP_TYPES = new Set([
     "epic",
     "feature",
@@ -147,53 +148,12 @@ function validateGetFields(fields, runtimeMetadataKeys, id) {
     if (fields === null) {
         return;
     }
-    const itemFields = new Set([
-        ...ITEM_METADATA_KEY_ORDER,
-        ...runtimeMetadataKeys,
-        "notes_count",
-        "tests_count",
-        "collection_counts",
-    ]);
-    const allowedRootFields = new Set([
-        "body",
-        "linked",
-        "claim_state",
-        "children",
-        "schedule",
-    ]);
-    const allowedLinkedFields = new Set([
-        "linked.files",
-        "linked.tests",
-        "linked.docs",
-    ]);
-    const allowedClaimStateFields = new Set([
-        "claim_state.claimed",
-        "claim_state.assignee",
-        "claim_state.last_claim",
-        "claim_state.last_release",
-    ]);
-    const allowedScheduleFields = new Set([
-        "schedule.deadline",
-        "schedule.start_at",
-        "schedule.end_at",
-        "schedule.location",
-        "schedule.reminders",
-        "schedule.events",
-    ]);
-    const allowedValues = [
-        ...[...itemFields].flatMap((field) => [field, `item.${field}`]),
-        ...allowedRootFields,
-        ...allowedLinkedFields,
-        ...allowedClaimStateFields,
-        ...allowedScheduleFields,
-    ].sort();
+    const allowedValues = listGetProjectionFields(runtimeMetadataKeys);
+    const allowed = new Set(allowedValues);
     const unknown = fields.filter((field) => {
         const normalized = normalizeGetField(field);
-        return (!itemFields.has(normalized) &&
-            !allowedRootFields.has(normalized) &&
-            !allowedLinkedFields.has(normalized) &&
-            !allowedClaimStateFields.has(normalized) &&
-            !allowedScheduleFields.has(normalized));
+        return (!allowed.has(field) &&
+            !allowed.has(normalized));
     });
     if (unknown.length > 0) {
         const suggestedRetryArguments = [
@@ -275,10 +235,16 @@ function fieldsIncludeRoot(fields, name) {
         return normalized === name || normalized.startsWith(`${name}.`);
     });
 }
-function resolveGetProjection(options) {
+function resolveGetProjection(options, id) {
     if (options.full &&
         (options.fields !== undefined || options.depth !== undefined)) {
-        throw new PmCliError("Get projection options are mutually exclusive; remove the extra projection flag and retry.", EXIT_CODE.USAGE);
+        throw new PmCliError("Get projection options are mutually exclusive; remove the extra projection flag and retry.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: renderPmCommand(["get", id, "--full"]),
+                suggested_retry_args: ["get", id, "--full"],
+            },
+        });
     }
     if (options.tree !== true && options.treeDepth !== undefined) {
         throw new PmCliError("Get --tree-depth requires --tree", EXIT_CODE.USAGE);
@@ -414,7 +380,7 @@ async function buildGetTree(context, options, treeDepth, global) {
 }
 /** Implements run get for the public runtime surface of this module. */
 export async function runGet(id, global, options = {}) {
-    const projection = resolveGetProjection(options);
+    const projection = resolveGetProjection(options, id);
     const context = await loadGetItemContext(id, global, options.at);
     validateGetProjectionFields(projection.fields, context.settings, context.historical !== undefined, context.locatedId);
     const includeBody = shouldIncludeGetField({ ...projection, field: "body" });
@@ -482,4 +448,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=1ba3eb17-c44c-5b62-8ae0-c2506fca9c62
+//# debugId=16d0a1cf-467d-5041-ab36-e2a9033a9342

package/dist/sdk/query/list.d.ts

@@ -5,6 +5,8 @@ import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js"
 import type { GlobalOptions } from "../../core/shared/command-types.js";
 import type { ItemMetadata, ItemStatus } from "../../types/index.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
+import { type ListCommandName, type ListProjectionMode } from "./projection-contracts.js";
+export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, type ListCommandName, type ListProjectionMode, } from "./projection-contracts.js";
 /** Documents the list options payload exchanged by command, SDK, and package integrations. */
 export interface ListOptions extends SharedItemFilterOptions {
     /** Value that configures or reports ids for this contract. */
@@ -62,6 +64,10 @@ export interface ListOptions extends SharedItemFilterOptions {
     /** Value that configures or reports filter metadata missing for this contract. */
     filterMetadataMissing?: boolean;
 }
+/** Adapter-only list context that never expands the public SDK options contract. */
+interface ListRuntimeOptions extends ListOptions {
+    projectionCommand?: ListCommandName;
+}
 /** Extract the missing-metadata selection filters from list/update-many options. */
 export declare const resolveMissingMetadataFilters: (options: {
     filterAcMissing?: boolean;
@@ -114,8 +120,6 @@ export interface ListProjectedItemCore {
 export type ListProjectedItem = ListProjectedItemCore & Record<string, unknown>;
 /** Honest union of item shapes returned by the list engine. */
 export type ListResultItem = ListedItem | ListTreeItem | ListProjectedItem;
-/** Stable projection names emitted by list envelopes and command contracts. */
-export type ListProjectionMode = "full" | "compact" | "brief" | "fields";
 interface ListProjectionConfig {
     mode: ListProjectionMode;
     fields: string[];
@@ -128,23 +132,6 @@ export type ListSortField = (typeof LIST_SORT_FIELDS)[number];
 export declare const LIST_SORT_ORDER_VALUES: readonly ["asc", "desc"];
 /** Restricts list sort order values accepted by command, SDK, and storage contracts. */
 export type ListSortOrder = (typeof LIST_SORT_ORDER_VALUES)[number];
-/** Stable field order for the compact list projection. */
-export declare const DEFAULT_COMPACT_LIST_FIELDS: readonly ["id", "title", "status", "type", "priority", "parent", "updated_at"];
-/** Stable field order for the agent-optimized brief list projection. */
-export declare const BRIEF_LIST_FIELDS: readonly ["id", "status", "type", "title"];
-/** Machine-readable default projection contract for every list command. */
-export declare const LIST_COMMAND_DEFAULT_PROJECTIONS: {
-    readonly list: "brief";
-    readonly "list-all": "full";
-    readonly "list-draft": "full";
-    readonly "list-open": "brief";
-    readonly "list-in-progress": "brief";
-    readonly "list-blocked": "brief";
-    readonly "list-closed": "full";
-    readonly "list-canceled": "full";
-};
-/** Command names whose output defaults are described by the list projection contract. */
-export type ListCommandName = keyof typeof LIST_COMMAND_DEFAULT_PROJECTIONS;
 interface ListResultBase {
     items: ListResultItem[];
     count: number;
@@ -244,7 +231,7 @@ declare function resolveListUpdatedAfter(options: ListOptions): string | undefin
 declare function parseIdsFilter(raw: unknown): Set<string> | undefined;
 declare function parseOffset(raw: string | undefined): number | undefined;
 declare function parseFieldSelectors(raw: string | undefined): string[] | undefined;
-declare function parseProjectionConfig(options: ListOptions): ListProjectionConfig;
+declare function parseProjectionConfig(options: ListRuntimeOptions, invokedCommand?: ListCommandName): ListProjectionConfig;
 declare function normalizeProjectionField(field: string): string;
 declare function parseSortField(raw: string | undefined): ListSortField | undefined;
 declare function parseSortOrder(raw: string | undefined): ListSortOrder | undefined;
@@ -309,4 +296,3 @@ export declare const _testOnly: {
     trimNonEmpty: typeof trimNonEmpty;
     withTreeMetadata: typeof withTreeMetadata;
 };
-export {};

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]="e2cb56ba-2f89-5589-8abf-f08cc7fa2b6b")}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]="67c5ff91-1c04-5506-ae5b-32f6552f1d07")}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";
@@ -18,7 +18,7 @@ import { collectRuntimeFilterValues, matchesRuntimeFilters, } from "../../core/s
 import { hasMissingMetadataFilter, itemMatchesMissingMetadata, lifecycleClassifierFromStatusRegistry, } from "../../core/governance/metadata-coverage.js";
 import { contentFiltersNeedBody, contentFiltersNeedCollections, hasContentFieldFilter, itemMatchesContentFilters, } from "../../core/governance/content-fields.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
-import { EXIT_CODE, ITEM_METADATA_KEY_ORDER, } from "../../core/shared/constants.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { compareTimestampStrings, matchesTimestampFilters, nowIso, resolveIsoOrRelative, } from "../../core/shared/time.js";
 import { listAllItemMetadata, listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
@@ -28,6 +28,8 @@ import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { LIST_FILTER_FLAG_CONTRACTS } from "../cli-contracts/flag-contracts.js";
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, selectCursorSemanticOptions, } from "../pagination.js";
+import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, listListProjectionFields, } from "./projection-contracts.js";
+export { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, listListProjectionFields, } from "./projection-contracts.js";
 /** Extract the missing-metadata selection filters from list/update-many options. */
 export const resolveMissingMetadataFilters = (options) => {
     return {
@@ -134,35 +136,6 @@ export const LIST_SORT_FIELDS = [
 ];
 /** Supported values accepted by the list sort order contract. */
 export const LIST_SORT_ORDER_VALUES = ["asc", "desc"];
-/** Stable field order for the compact list projection. */
-export const DEFAULT_COMPACT_LIST_FIELDS = [
-    "id",
-    "title",
-    "status",
-    "type",
-    "priority",
-    "parent",
-    "updated_at",
-];
-/** Stable field order for the agent-optimized brief list projection. */
-export const BRIEF_LIST_FIELDS = ["id", "status", "type", "title"];
-/** Machine-readable default projection contract for every list command. */
-export const LIST_COMMAND_DEFAULT_PROJECTIONS = {
-    list: "brief",
-    "list-all": "full",
-    "list-draft": "full",
-    "list-open": "brief",
-    "list-in-progress": "brief",
-    "list-blocked": "brief",
-    "list-closed": "full",
-    "list-canceled": "full",
-};
-const TREE_METADATA_FIELDS = [
-    "tree_depth",
-    "tree_parent",
-    "tree_children",
-    "tree_title",
-];
 // A projection that selects any heavy collection field (or `--full`, which returns
 // items verbatim) must load the full metadata; everything else takes the light path.
 // Sourced from the single HEAVY_METADATA_KEYS definition in the cache layer so the
@@ -479,7 +452,7 @@ function parseFieldSelectors(raw) {
     }
     return [...new Set(selectors)];
 }
-function parseProjectionConfig(options) {
+function parseProjectionConfig(options, invokedCommand = options.projectionCommand ?? "list") {
     const compactRequested = options.compact === true;
     const briefRequested = options.brief === true;
     const fullRequested = options.full === true;
@@ -489,7 +462,13 @@ function parseProjectionConfig(options) {
         Number(fullRequested) +
         Number(fieldSelectors !== undefined);
     if (enabledModes > 1) {
-        throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.", EXIT_CODE.USAGE);
+        throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.", EXIT_CODE.USAGE, {
+            code: "projection_options_mutually_exclusive",
+            recovery: {
+                suggested_retry: `pm ${invokedCommand} --brief`,
+                suggested_retry_args: [invokedCommand, "--brief"],
+            },
+        });
     }
     if (fullRequested) {
         return {
@@ -512,7 +491,9 @@ function parseProjectionConfig(options) {
     if (fieldSelectors) {
         return {
             mode: "fields",
-            fields: fieldSelectors,
+            fields: [
+                ...new Set(fieldSelectors.map((field) => normalizeProjectionField(field))),
+            ],
         };
     }
     return {
@@ -523,19 +504,12 @@ function parseProjectionConfig(options) {
 function normalizeProjectionField(field) {
     return field.startsWith("item.") ? field.slice("item.".length) : field;
 }
-function validateListProjectionFields(projection, runtimeMetadataKeys) {
+function validateListProjectionFields(projection, runtimeMetadataKeys, invokedCommand) {
     if (projection.mode !== "fields") {
         return;
     }
-    const allowed = new Set([
-        ...ITEM_METADATA_KEY_ORDER,
-        "body",
-        ...TREE_METADATA_FIELDS,
-        ...runtimeMetadataKeys,
-    ]);
-    const allowedValues = [...allowed]
-        .flatMap((field) => [field, `item.${field}`])
-        .sort();
+    const allowedValues = listListProjectionFields(runtimeMetadataKeys);
+    const allowed = new Set(allowedValues.map((field) => normalizeProjectionField(field)));
     const unknown = projection.fields.filter((field) => !allowed.has(normalizeProjectionField(field)));
     if (unknown.length > 0) {
         throw new PmCliError(`Unknown list --fields value(s): ${unknown.join(", ")}`, EXIT_CODE.USAGE, {
@@ -547,9 +521,9 @@ function validateListProjectionFields(projection, runtimeMetadataKeys) {
             ],
             recovery: {
                 allowed_values: allowedValues,
-                suggested_retry: "pm list --fields id,title,status --limit 10",
+                suggested_retry: `pm ${invokedCommand} --fields id,title,status --limit 10`,
                 suggested_retry_args: [
-                    "list",
+                    invokedCommand,
                     "--fields",
                     "id,title,status",
                     "--limit",
@@ -923,8 +897,9 @@ async function resolveListRuntimeContext(options, global) {
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const runtimeFieldRegistry = resolveRuntimeFieldRegistry(settings.schema);
-    const projection = parseProjectionConfig(options);
-    validateListProjectionFields(projection, runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions));
+    const invokedCommand = options.projectionCommand ?? "list";
+    const projection = parseProjectionConfig(options, invokedCommand);
+    validateListProjectionFields(projection, runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions), invokedCommand);
     return {
         pmRoot,
         settings,
@@ -1035,7 +1010,18 @@ async function tryLoadIndexedListPage(params) {
         "stream",
         "includeBody",
         "excludeTerminal",
+        "dependencyBlocked",
         "noTruncate",
+        "projectionCommand",
+        "truncate",
+        "notes",
+        "learnings",
+        "files",
+        "docs",
+        "tests",
+        "comments",
+        "deps",
+        "linkedCommand",
     ]);
     const projectionNeedsHeavyData = [
         runtime.projection.mode === "full",
@@ -1257,4 +1243,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=e2cb56ba-2f89-5589-8abf-f08cc7fa2b6b
+//# debugId=67c5ff91-1c04-5506-ae5b-32f6552f1d07

package/dist/sdk/query/projection-contracts.d.ts

@@ -0,0 +1,33 @@
+/** Stable projection names emitted by list envelopes and command contracts. */
+export type ListProjectionMode = "full" | "compact" | "brief" | "fields";
+/** Stable field order for the compact list projection. */
+export declare const DEFAULT_COMPACT_LIST_FIELDS: readonly ["id", "title", "status", "type", "priority", "parent", "updated_at"];
+/** Stable field order for the agent-optimized brief list projection. */
+export declare const BRIEF_LIST_FIELDS: readonly ["id", "status", "type", "title"];
+/** Machine-readable default projection contract for every list command. */
+export declare const LIST_COMMAND_DEFAULT_PROJECTIONS: {
+    readonly list: "brief";
+    readonly "list-all": "full";
+    readonly "list-draft": "full";
+    readonly "list-open": "brief";
+    readonly "list-in-progress": "brief";
+    readonly "list-blocked": "brief";
+    readonly "list-closed": "full";
+    readonly "list-canceled": "full";
+};
+/** Command names whose output defaults are described by the list projection contract. */
+export type ListCommandName = keyof typeof LIST_COMMAND_DEFAULT_PROJECTIONS;
+/** Return every accepted list projection selector for core and runtime metadata. */
+export declare function listListProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];
+/** Canonical get depth values. The CLI also accepts full as an alias for deep. */
+export declare const GET_DEPTH_VALUES: readonly ["brief", "standard", "deep"];
+/** Return every accepted get projection selector for core and runtime metadata. */
+export declare function listGetProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];
+/** Stable field order for compact search results. */
+export declare const DEFAULT_COMPACT_SEARCH_FIELDS: readonly ["id", "title", "status", "type", "priority", "updated_at", "score", "matched_fields"];
+/** Search-result fields that live beside the nested item projection. */
+export declare const SEARCH_HIT_FIELD_KEYS: readonly ["score", "matched_fields", "highlights"];
+/** Core item fields accepted by explicit search projections. */
+export declare const SEARCH_ITEM_FIELD_KEYS: readonly ["id", "title", "description", "type", "status", "priority", "tags", "created_at", "updated_at", "deadline", "assignee", "author", "estimated_minutes", "acceptance_criteria", "dependencies", "comments", "notes", "learnings", "reminders", "events", "files", "tests", "docs", "close_reason", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blocked_by", "blocked_reason", "reporter", "severity", "environment", "repro_steps", "resolution", "expected_result", "actual_result", "affected_version", "fixed_version", "component", "regression", "customer_impact", "definition_of_ready", "order", "rank", "goal", "objective", "value", "impact", "outcome", "why_now", "plan"];
+/** Return every accepted search projection selector for core and runtime metadata. */
+export declare function listSearchProjectionFields(runtimeMetadataKeys?: Iterable<string>): string[];