@unbrained/pm-cli 2026.8.21 → 2026.8.22

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]="361f891a-5f10-529c-8161-dc5193c7e12a")}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]="93e8c187-e198-50fc-bf2c-7dae2ea42219")}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";
@@ -27,6 +27,8 @@ import { queryItemMetadataIndex } from "../../core/store/item-metadata-query-ind
 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 { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { collectHierarchyRelations, indexHierarchyRelations, } from "../graph/hierarchy-integrity.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";
@@ -640,7 +642,9 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         parentFilter: options.parent?.trim(),
         treeEnabled: options.tree === true,
         sprintFilter: parseStringFilterSet(options.sprint, { label: "--sprint" }),
-        releaseFilter: parseStringFilterSet(options.release, { label: "--release" }),
+        releaseFilter: parseStringFilterSet(options.release, {
+            label: "--release",
+        }),
         missingMetadataFilters,
         missingMetadataActive: hasMissingMetadataFilter(missingMetadataFilters),
         lifecycleClassifier: lifecycleClassifierFromStatusRegistry(statusRegistry),
@@ -648,12 +652,6 @@ function resolveListFilterSet(status, options, typeRegistry, statusRegistry) {
         contentFiltersActive: hasContentFieldFilter(contentFieldFilters),
     };
 }
-function matchesListScalarFilters(item, filters, statusRegistry) {
-    return (matchesListIdentityFilters(item, filters, statusRegistry) &&
-        matchesListDateFilters(item, filters) &&
-        matchesListAssigneeFilterSet(item, filters) &&
-        matchesListScopeFilters(item, filters));
-}
 function matchesListIdentityFilters(item, filters, statusRegistry) {
     if (filters.idsFilter && !filters.idsFilter.has(item.id))
         return false;
@@ -681,10 +679,17 @@ function matchesListAssigneeFilterSet(item, filters) {
     return (filters.assigneeFilter === undefined ||
         (item.assignee !== undefined && filters.assigneeFilter.has(item.assignee)));
 }
-function matchesListScopeFilters(item, filters) {
+function matchesListScopeFilters(item, filters, parentsByChild) {
+    const scalarParent = item.parent?.trim().toLowerCase();
+    const logicalParentIds = [
+        ...new Set([
+            ...(parentsByChild?.get(item.id.trim().toLowerCase()) ?? []),
+            ...(scalarParent ? [scalarParent] : []),
+        ]),
+    ];
     if (filters.parentFilter !== undefined &&
         !filters.treeEnabled &&
-        item.parent !== filters.parentFilter)
+        !logicalParentIds.includes(filters.parentFilter.trim().toLowerCase()))
         return false;
     if (filters.sprintFilter !== undefined &&
         (item.sprint === undefined || !filters.sprintFilter.has(item.sprint)))
@@ -692,8 +697,11 @@ function matchesListScopeFilters(item, filters) {
     return (filters.releaseFilter === undefined ||
         (item.release !== undefined && filters.releaseFilter.has(item.release)));
 }
-function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters) {
-    if (!matchesListScalarFilters(item, filters, statusRegistry)) {
+function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild) {
+    if (!matchesListIdentityFilters(item, filters, statusRegistry) ||
+        !matchesListDateFilters(item, filters) ||
+        !matchesListAssigneeFilterSet(item, filters) ||
+        !matchesListScopeFilters(item, filters, parentsByChild)) {
         return false;
     }
     if (filters.missingMetadataActive &&
@@ -709,9 +717,9 @@ function matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters
     }
     return true;
 }
-function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters) {
+function applyFilters(items, status, options, typeRegistry, statusRegistry, runtimeFieldFilters, parentsByChild) {
     const filters = resolveListFilterSet(status, options, typeRegistry, statusRegistry);
-    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters));
+    return items.filter((item) => matchesListFilterSet(item, filters, statusRegistry, runtimeFieldFilters, parentsByChild));
 }
 function trimNonEmpty(value) {
     if (typeof value !== "string") {
@@ -720,10 +728,12 @@ function trimNonEmpty(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-function withTreeMetadata(item, depth, childCount) {
+function withTreeMetadata(item, depth, childCount, parentId) {
     const itemRecord = toItemRecord(item);
     const title = typeof itemRecord.title === "string" ? itemRecord.title : "";
-    const parent = trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ?? null;
+    const parent = parentId ??
+        trimNonEmpty(typeof itemRecord.parent === "string" ? itemRecord.parent : undefined) ??
+        null;
     return {
         ...item,
         tree_depth: depth,
@@ -732,47 +742,73 @@ function withTreeMetadata(item, depth, childCount) {
         tree_title: `${"  ".repeat(depth)}${title}`,
     };
 }
-function orderItemsAsTree(sortedItems, parentRoot, maxDepth) {
+function buildListTreeIndexes(sortedItems, hierarchyIndexes) {
     const byId = new Map();
     const childrenByParent = new Map();
     for (const item of sortedItems) {
-        byId.set(item.id, item);
-        const parentId = trimNonEmpty(item.parent);
-        if (!parentId) {
-            continue;
-        }
-        const bucket = childrenByParent.get(parentId);
-        if (bucket) {
-            bucket.push(item);
-        }
-        else {
-            childrenByParent.set(parentId, [item]);
+        const itemId = item.id.trim().toLowerCase();
+        byId.set(itemId, item);
+        const parentIds = hierarchyIndexes
+            ? (hierarchyIndexes.parents_by_child.get(itemId) ?? [])
+            : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+        for (const parentId of parentIds) {
+            const children = childrenByParent.get(parentId) ?? [];
+            children.push(item);
+            childrenByParent.set(parentId, children);
         }
     }
-    const roots = parentRoot
-        ? [...(childrenByParent.get(parentRoot) ?? [])]
+    return { byId, childrenByParent };
+}
+function resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes) {
+    return parentRoot
+        ? [...(childrenByParent.get(parentRoot.toLowerCase()) ?? [])]
         : sortedItems.filter((item) => {
-            const parentId = trimNonEmpty(item.parent);
-            return !parentId || !byId.has(parentId);
+            const parentIds = hierarchyIndexes
+                ? (hierarchyIndexes.parents_by_child.get(item.id.trim().toLowerCase()) ?? [])
+                : [trimNonEmpty(item.parent)?.toLowerCase()].filter((value) => value !== undefined);
+            return parentIds.every((parentId) => !byId.has(parentId));
         });
+}
+function orderItemsAsTree(sortedItems, parentRoot, maxDepth, hierarchyIndexes, completeItems = sortedItems) {
+    const { byId, childrenByParent } = buildListTreeIndexes(sortedItems, hierarchyIndexes);
+    const roots = resolveListTreeRoots(sortedItems, parentRoot, byId, childrenByParent, hierarchyIndexes);
     const ordered = [];
     const visited = new Set();
-    const pushNode = (node, depth) => {
-        if (visited.has(node.id)) {
-            return;
-        }
-        visited.add(node.id);
-        const children = childrenByParent.get(node.id) ?? [];
-        ordered.push(withTreeMetadata(node, depth, children.length));
-        if (maxDepth !== undefined && depth >= maxDepth) {
-            return;
+    const canonicalIdByLowercase = new Map(completeItems.map((item) => [item.id.trim().toLowerCase(), item.id.trim()]));
+    const pending = [...roots].reverse().map((node) => ({
+        node,
+        depth: 0,
+        parentId: parentRoot === undefined
+            ? undefined
+            : (canonicalIdByLowercase.get(parentRoot.trim().toLowerCase()) ??
+                parentRoot.trim()),
+    }));
+    while (pending.length > 0) {
+        const { node, depth, parentId } = pending.pop();
+        const nodeId = node.id.trim().toLowerCase();
+        if (visited.has(nodeId))
+            continue;
+        visited.add(nodeId);
+        const children = childrenByParent.get(nodeId) ?? [];
+        ordered.push(withTreeMetadata(node, depth, children.length, parentId));
+        if (maxDepth !== undefined && depth >= maxDepth)
+            continue;
+        for (const child of [...children].reverse()) {
+            pending.push({
+                node: child,
+                depth: depth + 1,
+                parentId: canonicalIdByLowercase.get(nodeId),
+            });
         }
-        for (const child of children) {
-            pushNode(child, depth + 1);
+    }
+    if (parentRoot === undefined && maxDepth === undefined) {
+        for (const item of sortedItems) {
+            const itemId = item.id.trim().toLowerCase();
+            if (visited.has(itemId))
+                continue;
+            visited.add(itemId);
+            ordered.push(withTreeMetadata(item, 0, childrenByParent.get(itemId)?.length ?? 0));
         }
-    };
-    for (const root of roots) {
-        pushNode(root, 0);
     }
     return ordered;
 }
@@ -1136,8 +1172,12 @@ export async function runList(status, options, global) {
     let page = indexedPage;
     if (!page) {
         const items = await loadListItems(options, runtime, listWarnings);
+        const needsHierarchyIndexes = ordering.treeEnabled || trimNonEmpty(options.parent) !== undefined;
+        const hierarchyIndexes = needsHierarchyIndexes
+            ? indexHierarchyRelations(collectHierarchyRelations(items, resolveWorkspaceRelationshipKindRegistry()))
+            : undefined;
         appendUnknownTagWarning(items, options.tag, listWarnings);
-        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters);
+        const filtered = applyFilters(items, statusSelection.resolvedStatus, statusSelection.effectiveOptions, runtime.typeRegistry, runtime.statusRegistry, runtime.runtimeFieldFilters, hierarchyIndexes?.parents_by_child);
         // Edge-aware blocked selection (GH-578): classify against the complete
         // loaded corpus so terminal blocker targets count as satisfied, then narrow
         // the already-filtered rows to the shared blocked set.
@@ -1149,7 +1189,7 @@ export async function runList(status, options, global) {
             : filtered;
         const sorted = sortItems(scoped, ordering.sortField, ordering.sortOrder, runtime.statusRegistry);
         const ordered = ordering.treeEnabled
-            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth)
+            ? orderItemsAsTree(sorted, ordering.parentRoot, ordering.treeDepth, hierarchyIndexes, items)
             : sorted;
         page = pageAndProjectListItems(ordered, options, runtime.projection, ordering.treeEnabled, buildListCursorFingerprint(statusSelection.filtersStatus, options, ordering));
     }
@@ -1241,4 +1281,4 @@ export const _testOnly = {
     withTreeMetadata,
 };
 //# sourceMappingURL=list.js.map
-//# debugId=361f891a-5f10-529c-8161-dc5193c7e12a
+//# debugId=93e8c187-e198-50fc-bf2c-7dae2ea42219

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

@@ -5,7 +5,7 @@ export declare const PM_READ_OUTPUT_DIMENSIONS: readonly ["include", "amount", "
 /** One member of the universal read-output dimension set. */
 export type PmReadOutputDimension = (typeof PM_READ_OUTPUT_DIMENSIONS)[number];
 /** Built-in command roots whose primary operation is a read. */
-export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "package-catalog", "package-manage", "comments-audit", "assurance"];
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["list", "context", "search", "get", "next", "health", "deps", "graph", "history", "activity", "validate", "events", "contracts", "comments", "notes", "files", "docs", "stats", "aggregate", "duplicates", "package-catalog", "package-manage", "comments-audit", "assurance"];
 /** Built-in read command supported by the universal output contract. */
 export type PmReadOutputSurface = (typeof PM_READ_OUTPUT_SURFACES)[number];
 /** Canonical output controls accepted by every built-in read action. */
@@ -81,6 +81,8 @@ export interface PmResolvedReadOutputDimensions {
     cost?: PmResolvedReadOutputDimension<number | "unbounded">;
     /** Requested static encoding or a retained legacy streaming behavior. */
     encoding?: PmResolvedReadOutputDimension<"json" | "toon" | "stream">;
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility flags observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for observed compatibility flags. */
@@ -102,6 +104,8 @@ export interface PmReadOutputReceipt {
     budget_tokens?: number;
     /** Deterministic precedence used during resolution. */
     precedence: readonly ["canonical", "legacy", "intent", "default"];
+    /** Canonical CLI options observed on the invocation. */
+    canonical_options_used?: string[];
     /** Compatibility options observed on the invocation. */
     legacy_aliases_used: string[];
     /** One-line migration instructions for compatibility options. */

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

@@ -5,7 +5,7 @@
  * surface without coupling package authors to command-specific option names.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b3c001df-9891-5cf7-990b-8d9da7b51801")}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]="a1272c1f-c03e-580c-8c44-6b3ddeedd240")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { compactReadOutputToBudget, estimateReadOutputTokens, updateReadOutputReceiptEstimate, } from "./read-output-budget.js";
@@ -43,6 +43,7 @@ export const PM_READ_OUTPUT_SURFACES = [
     "docs",
     "stats",
     "aggregate",
+    "duplicates",
     "package-catalog",
     "package-manage",
     "comments-audit",
@@ -60,6 +61,7 @@ const CANONICAL_OPTIONS = {
     cost: "--output-budget",
     encoding: "--output-format",
 };
+const READ_OUTPUT_INVOCATION_PROVENANCE = Symbol.for("pm.readOutputInvocationProvenance");
 /** Canonical CLI flags that opt a read invocation into universal output shaping. */
 export const PM_READ_OUTPUT_OPTION_FLAGS = Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => CANONICAL_OPTIONS[dimension]));
 /** Canonical control that composes the four per-call dimensions across reads. */
@@ -136,6 +138,7 @@ const LEGACY_FLAGS_BY_COMMAND = {
     docs: {},
     stats: {},
     aggregate: {},
+    duplicates: { amount: ["--limit"] },
     "package-catalog": {},
     "package-manage": {},
     "comments-audit": {},
@@ -363,14 +366,32 @@ export function applyReadOutputIncludeModes(command, includeValue, commandOption
     const modeOptions = readOutputIncludeModeOptions(command);
     const selectors = [];
     const modes = [];
+    const optionsWithProvenance = commandOptions;
+    const existingProvenance = optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE];
+    const canonicalModes = new Set(existingProvenance?.canonical_include_modes ?? []);
+    const explicitLegacyAliases = new Set(existingProvenance?.explicit_legacy_aliases ?? []);
     for (const token of requested) {
         const option = modeOptions.get(token);
         if (option === undefined) {
             selectors.push(token);
             continue;
         }
+        const legacyFlag = `--${token.replaceAll("_", "-")}`;
+        if (isRequestedOption(readOption(commandOptions, legacyFlag))) {
+            explicitLegacyAliases.add(legacyFlag);
+        }
         commandOptions[option] = true;
         modes.push(token);
+        canonicalModes.add(token);
+    }
+    if (modes.length > 0) {
+        optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE] = {
+            canonical_include_modes: [...canonicalModes],
+            explicit_legacy_aliases: [...explicitLegacyAliases],
+            ...(existingProvenance?.cli_invocation_observed === true
+                ? { cli_invocation_observed: true }
+                : {}),
+        };
     }
     return { selectors, modes };
 }
@@ -430,8 +451,10 @@ function positiveInteger(value) {
             : Number.NaN;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
 }
-function resolveLegacyDimension(contract, options, usable) {
+function resolveLegacyDimension(contract, options, usable, ignore) {
     for (const alias of contract.legacy_aliases) {
+        if (ignore(alias.flag))
+            continue;
         const value = readOption(options, alias.flag);
         const candidate = { value, flag: alias.flag };
         if (isRequestedOption(value) && usable(candidate))
@@ -496,12 +519,43 @@ function resolveEncodingValue(canonical, legacy) {
         ? { source: "legacy", value: legacy.value }
         : undefined;
 }
+function shouldIgnoreReadOutputLegacyAlias(provenance, dimension, flag) {
+    if (!provenance)
+        return false;
+    const explicitLegacyAliases = new Set(provenance.explicit_legacy_aliases);
+    if (provenance.cli_invocation_observed === true) {
+        return !explicitLegacyAliases.has(flag);
+    }
+    const forwardedIncludeAliases = new Set(provenance.canonical_include_modes.map((mode) => `--${mode.replaceAll("_", "-")}`));
+    return (dimension === "include" &&
+        forwardedIncludeAliases.has(flag) &&
+        !explicitLegacyAliases.has(flag));
+}
+function hasCompleteReadOutputIntent(command, legacyByDimension, provenance) {
+    const root = command
+        .trim()
+        .toLowerCase()
+        .replaceAll(/\s+/gu, " ")
+        .split(" ")[0];
+    return (root === "list-all" ||
+        legacyByDimension.amount?.flag === "--no-truncate" ||
+        legacyByDimension.include?.flag === "--full" ||
+        provenance?.canonical_include_modes.includes("full") === true);
+}
+function canonicalReadOutputOptionsUsed(resolvedByDimension, provenance) {
+    return PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => resolvedByDimension[dimension]?.source === "canonical" ||
+        (dimension === "include" &&
+            (provenance?.canonical_include_modes.length ?? 0) > 0)
+        ? [CANONICAL_OPTIONS[dimension]]
+        : []);
+}
 /** Resolve canonical and compatibility controls into the universal dimension set. */
 export function resolveReadOutputDimensions(command, options) {
     const normalizedCommand = resolveReadOutputSurface(command, options);
     if (!normalizedCommand)
         return undefined;
     const contract = SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);
+    const invocationProvenance = options[READ_OUTPUT_INVOCATION_PROVENANCE];
     const legacyResolvers = {
         include: (candidate) => resolveIncludeValue(undefined, candidate),
         amount: (candidate) => resolveAmountValue(undefined, candidate),
@@ -510,7 +564,7 @@ export function resolveReadOutputDimensions(command, options) {
     };
     const legacyByDimension = Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map((dimension) => [
         dimension,
-        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined),
+        resolveLegacyDimension(contract.dimensions[dimension], options, (candidate) => legacyResolvers[dimension](candidate) !== undefined, (flag) => shouldIgnoreReadOutputLegacyAlias(invocationProvenance, dimension, flag)),
     ]));
     const legacyAliasesUsed = PM_READ_OUTPUT_DIMENSIONS.flatMap((dimension) => {
         const resolved = legacyByDimension[dimension];
@@ -524,29 +578,31 @@ export function resolveReadOutputDimensions(command, options) {
         return [alias.migration_hint];
     });
     const encoding = resolveEncodingValue(options.outputFormat ?? options.output_format, legacyByDimension.encoding);
+    const include = resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include);
+    const amount = resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount);
     const explicitCost = resolveCostValue(options.outputBudget ?? options.output_budget, legacyByDimension.cost);
-    const completeResultIntent = command.trim().toLowerCase().replaceAll(/\s+/gu, " ").split(" ")[0] ===
-        "list-all" ||
-        legacyByDimension.amount?.flag === "--no-truncate" ||
-        legacyByDimension.include?.flag === "--full";
+    const completeResultIntent = hasCompleteReadOutputIntent(command, legacyByDimension, invocationProvenance);
     const budget = resolvePmCommandOutputBudget(command, {
         generateFallback: true,
     });
     const resolvedOutputFormat = encoding?.value === "json" || options.resolvedOutputFormat === "json"
         ? "json"
         : "toon";
+    const cost = explicitCost ??
+        (completeResultIntent
+            ? { source: "intent", value: "unbounded" }
+            : {
+                source: "default",
+                value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
+            });
+    const resolvedByDimension = { include, amount, cost, encoding };
     return {
         command: normalizedCommand,
-        include: resolveIncludeValue(options.outputInclude ?? options.output_include, legacyByDimension.include),
-        amount: resolveAmountValue(options.outputLimit ?? options.output_limit, legacyByDimension.amount),
-        cost: explicitCost ??
-            (completeResultIntent
-                ? { source: "intent", value: "unbounded" }
-                : {
-                    source: "default",
-                    value: budget.default_max_estimated_tokens_by_format[resolvedOutputFormat],
-                }),
+        include,
+        amount,
+        cost,
         encoding,
+        canonical_options_used: canonicalReadOutputOptionsUsed(resolvedByDimension, invocationProvenance),
         legacy_aliases_used: legacyAliasesUsed,
         migration_hints: migrationHints,
         precedence: READ_OUTPUT_PRECEDENCE,
@@ -732,8 +788,9 @@ function applyAmountBound(result, amount) {
     return bounded;
 }
 function requestedDimensions(resolved) {
-    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => resolved[dimension] !== undefined &&
-        resolved[dimension]?.source !== "default");
+    return PM_READ_OUTPUT_DIMENSIONS.filter((dimension) => (resolved[dimension] !== undefined &&
+        resolved[dimension]?.source !== "default") ||
+        resolved.canonical_options_used.includes(CANONICAL_OPTIONS[dimension]));
 }
 /** Stabilize the per-call and cross-call receipts in one complete envelope. */
 function attachReadOutputSessionContracts(result, state, receipt) {
@@ -847,6 +904,12 @@ function resolveBindingReadOutputBudget(resolved, session) {
     ];
     return budgets.sort((left, right) => left.tokens - right.tokens)[0];
 }
+function canonicalReadOutputReceiptFields(resolved) {
+    const canonicalOptions = resolved.canonical_options_used;
+    return canonicalOptions && canonicalOptions.length > 0
+        ? { canonical_options_used: canonicalOptions }
+        : {};
+}
 /** Build the smallest truthful omission envelope or reject an exhausted session. */
 function omitReadOutputForBudget(resolved, requested, session, bindingBudget, omittedResultEstimatedTokens) {
     const minimalReceipt = {
@@ -860,6 +923,7 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: [],
         migration_hints: [],
         estimated_tokens: 0,
@@ -893,10 +957,10 @@ function omitReadOutputForBudget(resolved, requested, session, bindingBudget, om
     return boundedOmission;
 }
 /** Decide whether shaping would add no value to an already-bounded result. */
-function canReturnReadOutputUnchanged(resolved, requested, session, result) {
+function canReturnReadOutputUnchanged(resolved, session, result) {
     if (session !== undefined)
         return false;
-    const canonicalRequestedCount = requested.filter((dimension) => resolved[dimension]?.source === "canonical").length;
+    const canonicalRequestedCount = resolved.canonical_options_used.length;
     if (resolved.cost?.value === "unbounded") {
         return (canonicalRequestedCount === (resolved.cost.source === "canonical" ? 1 : 0));
     }
@@ -1077,7 +1141,7 @@ export function applyReadOutputDimensions(command, options, result) {
         : undefined;
     const requested = requestedDimensions(resolved);
     if (cursor === undefined &&
-        canReturnReadOutputUnchanged(resolved, requested, session, result)) {
+        canReturnReadOutputUnchanged(resolved, session, result)) {
         return result;
     }
     const continuationReadyResult = attachValidateDiagnosticRowContract(resolved.command, result);
@@ -1095,6 +1159,7 @@ export function applyReadOutputDimensions(command, options, result) {
             }
             : {}),
         precedence: resolved.precedence,
+        ...canonicalReadOutputReceiptFields(resolved),
         legacy_aliases_used: resolved.legacy_aliases_used,
         migration_hints: resolved.migration_hints,
         estimated_tokens: 0,
@@ -1134,4 +1199,4 @@ export function resolveReadOutputEncoding(command, options) {
         : undefined;
 }
 //# sourceMappingURL=read-output-contracts.js.map
-//# debugId=b3c001df-9891-5cf7-990b-8d9da7b51801
+//# debugId=a1272c1f-c03e-580c-8c44-6b3ddeedd240

package/dist/sdk/relationship-context.js

@@ -5,7 +5,7 @@
  * packet for agents, custom tools, and presentation-layer adapters.
  */
 
-!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]="31a800f7-1374-5e7c-ad23-ae3d8ebcebe0")}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]="afdba960-ae43-52be-b21d-282dac1f22ff")}catch(e){}}();
 import { createQueryFingerprint, encodeQueryCursor, resolveQueryCursorStart, } from "./pagination.js";
 import { createRelationshipKindRegistry, } from "./relationships.js";
 /** Deterministic priority used when one node matches several semantic families. */
@@ -37,8 +37,7 @@ function explainDirectEdge(edge, node, registry) {
         return node === before ? "prerequisite" : "dependent";
     }
     if (definition?.hierarchy) {
-        // Legacy and JSON-parsed definitions may predate explicit hierarchy direction.
-        const sourceIsParent = (definition.hierarchyDirection ?? "source_parent") === "source_parent";
+        const sourceIsParent = definition.hierarchyDirection === "source_parent";
         const parent = sourceIsParent ? edge.source : edge.target;
         return node === parent ? "ancestor" : "descendant";
     }
@@ -283,4 +282,4 @@ export function buildRelationshipContext(graph, rootId, details, options = {}) {
     };
 }
 //# sourceMappingURL=relationship-context.js.map
-//# debugId=31a800f7-1374-5e7c-ad23-ae3d8ebcebe0
+//# debugId=afdba960-ae43-52be-b21d-282dac1f22ff

package/dist/sdk/relationships.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b1c32b57-0231-5bea-ade4-99247504f938")}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]="d7d44fba-603b-5ef2-8490-51112b929433")}catch(e){}}();
 import { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 export { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 function normalizeKind(kind) {
@@ -105,6 +105,17 @@ function assertRelationshipKindPayload(definition, kind) {
             definition.aliases.some((alias) => typeof alias !== "string")))
         throw new TypeError(`Invalid relationship aliases for ${kind}`);
 }
+function resolveRelationshipTraversal(definition) {
+    if (definition.traversal)
+        return definition.traversal;
+    // Dual-family extension kinds use ordering precedence, matching relationship
+    // context role classification. Explicit traversal always remains authoritative.
+    if (definition.ordering)
+        return "ordering";
+    if (definition.hierarchy)
+        return "hierarchy";
+    return definition.direction === "undirected" ? "association" : "semantic";
+}
 /** Mutable registry with immutable snapshots and collision-safe extension registration. */
 export class RelationshipKindRegistry {
     #definitions = new Map();
@@ -139,15 +150,11 @@ export class RelationshipKindRegistry {
         const normalized = Object.freeze({
             ...definition,
             kind,
-            traversal: definition.traversal ??
-                (definition.hierarchy
-                    ? "hierarchy"
-                    : definition.ordering
-                        ? "ordering"
-                        : definition.direction === "undirected"
-                            ? "association"
-                            : "semantic"),
+            traversal: resolveRelationshipTraversal(definition),
             hierarchy: definition.hierarchy ?? false,
+            hierarchyDirection: definition.hierarchy
+                ? (definition.hierarchyDirection ?? "source_parent")
+                : undefined,
             inverse,
             aliases: Object.freeze(aliases),
             payloadSchema: definition.payloadSchema
@@ -570,4 +577,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=b1c32b57-0231-5bea-ade4-99247504f938
+//# debugId=d7d44fba-603b-5ef2-8490-51112b929433

package/dist/sdk/runtime.d.ts

@@ -6,6 +6,7 @@
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, type EnsurePmGitignoreResult, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
+export * from "./cli-contracts/agent-output-contracts.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import type { ItemMetadata } from "../types/index.js";
 import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
@@ -155,7 +156,7 @@ export declare class PmClient {
     /** Return project tracker statistics with the same sections as `pm stats`. */
     stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options): ReadPromise<StatsResult, Options>;
     /** Discover existing duplicate clusters without mutating tracker state. */
-    duplicates(options?: DuplicatesCommandOptions): Promise<DuplicatesResult>;
+    duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options): ReadPromise<DuplicatesResult, Options>;
     /** List, add, edit, or delete item comments. */
     comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options): ReadPromise<CommentsResult, Options>;
     /** List or append private item notes. */
@@ -371,7 +372,7 @@ export declare function aggregate<Options extends ReadOptions<AggregateOptions>
 /** Return project tracker statistics with the same sections as `pm stats` without constructing a reusable client. */
 export declare function stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<StatsResult, Options>;
 /** Discover duplicate clusters without constructing a reusable client. */
-export declare function duplicates(options?: DuplicatesCommandOptions, clientOptions?: PmClientOptions): Promise<DuplicatesResult>;
+export declare function duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<DuplicatesResult, Options>;
 /** List, add, edit, or delete item comments without constructing a reusable client. */
 export declare function comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<CommentsResult, Options>;
 /** List or append private item notes without constructing a reusable client. */

package/dist/sdk/runtime.js

@@ -4,9 +4,10 @@
  * 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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}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]="a27b9b88-a8de-5e38-ab7f-dfcc61d1fad6")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
+export * from "./cli-contracts/agent-output-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
 import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
@@ -1944,4 +1945,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699
+//# debugId=a27b9b88-a8de-5e38-ab7f-dfcc61d1fad6