@unbrained/pm-cli 2026.8.19 → 2026.8.21

package/dist/sdk/query/get.js

@@ -4,8 +4,9 @@
  * 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]="ff82974e-a48d-5d18-893f-fb618e378795")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { getActiveExtensionRegistrations, toItemRecord, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, TYPE_TO_FOLDER, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, getHistoryPath, 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 +16,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 +149,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 +236,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);
@@ -297,9 +264,7 @@ function resolveGetProjection(options) {
 }
 async function loadGetItemContext(id, global, at) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     if (at !== undefined) {
@@ -414,7 +379,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 +447,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=1ba3eb17-c44c-5b62-8ae0-c2506fca9c62
+//# debugId=ff82974e-a48d-5d18-893f-fb618e378795

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

@@ -1,8 +1,3 @@
-/**
- * @module cli/commands/history
- *
- * Implements the pm history command surface and its agent-facing runtime behavior.
- */
 import { type HistoryDiffValueEntry, verifyHistoryChain, type GlobalOptions } from "../runtime-primitives.js";
 import { type HistoryVerificationResult } from "../history-read.js";
 export { readHistoryEntries } from "../history-read.js";

package/dist/sdk/query/history.js

@@ -4,8 +4,9 @@
  * Implements the pm history 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]="f18d7526-01eb-593b-bf50-788c08a35e5d")}catch(e){}}();
-import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, getSettingsPath, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } 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]="314adea1-6837-5eeb-abc3-57337a495221")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { pathExists, computeHistoryDiff, patchPathToChangedField, normalizeReplayPatchOps, verifyHistoryChain, enforceHistoryStreamPolicyForItem, EXIT_CODE, PmCliError, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, locateItem, readLocatedItem, getHistoryPath, getWorkspaceHistoryPath, inspectWorkspaceHistoryState, resolvePmRoot, readSettings, WORKSPACE_HISTORY_ID, } from "../runtime-primitives.js";
 import { readHistoryEntries, verifyHistoryEntries, } from "../history-read.js";
 export { readHistoryEntries } from "../history-read.js";
 import { parseLimit } from "./parsers.js";
@@ -39,9 +40,7 @@ function buildDiffEntries(entries, startIndex) {
 }
 async function resolveHistoryReadTarget(id, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const workspaceHistoryRequested = id.trim() === WORKSPACE_HISTORY_ID;
@@ -161,4 +160,4 @@ export async function runHistory(id, options, global) {
     return result;
 }
 //# sourceMappingURL=history.js.map
-//# debugId=f18d7526-01eb-593b-bf50-788c08a35e5d
+//# debugId=314adea1-6837-5eeb-abc3-57337a495221

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,8 +4,8 @@
  * 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){}}();
-import { pathExists } from "../../core/fs/fs-utils.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]="361f891a-5f10-529c-8161-dc5193c7e12a")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -18,16 +18,18 @@ 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";
 import { HEAVY_METADATA_KEYS, readItemMetadataDerivedIndexState, } from "../../core/store/item-metadata-cache.js";
 import { queryItemMetadataIndex } from "../../core/store/item-metadata-query-index.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { 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",
@@ -917,14 +891,13 @@ function buildListPageExtras(limit, hasMore, nextCursor) {
 }
 async function resolveListRuntimeContext(options, global) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     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 +1008,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 +1241,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=e2cb56ba-2f89-5589-8abf-f08cc7fa2b6b
+//# debugId=361f891a-5f10-529c-8161-dc5193c7e12a

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[];

package/dist/sdk/query/projection-contracts.js

@@ -0,0 +1,185 @@
+/**
+ * @module sdk/query/projection-contracts
+ *
+ * Declares dependency-light projection vocabularies for list, get, and search
+ * so contract-only SDK imports do not initialize query runtimes or storage.
+ */
+
+!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]="5bb71ec1-7eb1-558e-a965-acd779570c2e")}catch(e){}}();
+import { ITEM_METADATA_KEY_ORDER } from "../../core/shared/item-metadata-contract.js";
+/** 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",
+];
+/** Return every accepted list projection selector for core and runtime metadata. */
+export function listListProjectionFields(runtimeMetadataKeys = []) {
+    return [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            "body",
+            ...TREE_METADATA_FIELDS,
+            ...runtimeMetadataKeys,
+        ]),
+    ]
+        .flatMap((field) => [field, `item.${field}`])
+        .sort();
+}
+/** Canonical get depth values. The CLI also accepts full as an alias for deep. */
+export const GET_DEPTH_VALUES = ["brief", "standard", "deep"];
+const GET_ROOT_PROJECTION_FIELDS = [
+    "body",
+    "linked",
+    "claim_state",
+    "children",
+    "schedule",
+];
+const GET_LINKED_PROJECTION_FIELDS = [
+    "linked.files",
+    "linked.tests",
+    "linked.docs",
+];
+const GET_CLAIM_STATE_PROJECTION_FIELDS = [
+    "claim_state.claimed",
+    "claim_state.assignee",
+    "claim_state.last_claim",
+    "claim_state.last_release",
+];
+const GET_SCHEDULE_PROJECTION_FIELDS = [
+    "schedule.deadline",
+    "schedule.start_at",
+    "schedule.end_at",
+    "schedule.location",
+    "schedule.reminders",
+    "schedule.events",
+];
+/** Return every accepted get projection selector for core and runtime metadata. */
+export function listGetProjectionFields(runtimeMetadataKeys = []) {
+    const itemFields = [
+        ...new Set([
+            ...ITEM_METADATA_KEY_ORDER,
+            ...runtimeMetadataKeys,
+            "notes_count",
+            "tests_count",
+            "collection_counts",
+        ]),
+    ];
+    return [
+        ...itemFields.flatMap((field) => [field, `item.${field}`]),
+        ...GET_ROOT_PROJECTION_FIELDS,
+        ...GET_LINKED_PROJECTION_FIELDS,
+        ...GET_CLAIM_STATE_PROJECTION_FIELDS,
+        ...GET_SCHEDULE_PROJECTION_FIELDS,
+    ].sort();
+}
+/** Stable field order for compact search results. */
+export const DEFAULT_COMPACT_SEARCH_FIELDS = [
+    "id",
+    "title",
+    "status",
+    "type",
+    "priority",
+    "updated_at",
+    "score",
+    "matched_fields",
+];
+/** Search-result fields that live beside the nested item projection. */
+export const SEARCH_HIT_FIELD_KEYS = [
+    "score",
+    "matched_fields",
+    "highlights",
+];
+/** Core item fields accepted by explicit search projections. */
+export const SEARCH_ITEM_FIELD_KEYS = [
+    "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 function listSearchProjectionFields(runtimeMetadataKeys = []) {
+    const runtimeKeys = [...new Set(runtimeMetadataKeys)];
+    return [
+        ...SEARCH_HIT_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS,
+        ...SEARCH_ITEM_FIELD_KEYS.map((field) => `item.${field}`),
+        ...runtimeKeys,
+        ...runtimeKeys.map((field) => `item.${field}`),
+    ].sort();
+}
+//# sourceMappingURL=projection-contracts.js.map
+//# debugId=5bb71ec1-7eb1-558e-a965-acd779570c2e

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

@@ -1,6 +1,7 @@
 import type { RuntimeFieldRegistry } from "../../core/schema/runtime-schema.js";
 import type { SharedItemFilterOptions } from "./item-filter-options.js";
 import type { SearchMode } from "./search-rendering.js";
+export { DEFAULT_COMPACT_SEARCH_FIELDS, SEARCH_HIT_FIELD_KEYS, SEARCH_ITEM_FIELD_KEYS, listSearchProjectionFields, } from "./projection-contracts.js";
 /** Documents the search options payload exchanged by command, SDK, and package integrations. */
 export interface SearchOptions extends SharedItemFilterOptions {
     /** Value that configures or reports mode for this contract. */
@@ -60,7 +61,7 @@ export declare function normalizeSearchPhrase(value: string): string;
 /** Parse an optional deadline filter. */
 export declare function parseSearchDeadline(raw: string | undefined, fieldLabel: string): string | undefined;
 /** Resolve mutually exclusive compact, full, or explicit-field projection. */
-export declare function parseSearchProjection(options: SearchOptions): SearchProjectionConfig;
+export declare function parseSearchProjection(options: SearchOptions, query?: string): SearchProjectionConfig;
 /** Validate explicit projection fields against core and runtime metadata. */
 export declare function validateSearchProjectionFields(projection: SearchProjectionConfig, runtimeFieldRegistry: RuntimeFieldRegistry, query?: string): void;
 /** Parse a non-empty normalized query into lexical tokens. */