@unbrained/pm-cli 2026.9.4 → 2026.9.6

package/dist/sdk/query/next.js

@@ -9,9 +9,10 @@
  * re-deriving readiness from a full `pm context` snapshot every turn.
  */
 
-!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]="b0f3d72c-ff0b-59bb-a6bc-8476eb9fb6c1")}catch(e){}}();
-import { collectBlockedByIds, computeActionabilityReport, } from "../actionability.js";
-import { resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, nowIso, normalizeStatusInput, normalizeStatusForRegistry, 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]="6035e85b-81ed-512e-b291-b0d86af1848b")}catch(e){}}();
+import { collectBlockedByIds, computeActionabilityReport, resolveItemExecutionRole, selectActionableEntries, } from "../actionability.js";
+import { resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, nowIso, normalizeStatusInput, normalizeStatusForRegistry, resolvePmRoot, readSettings, resolveAuthor, resolveItemTypeRegistry, } from "../runtime-primitives.js";
+import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { parseIntegerLimit } from "./parsers.js";
 import { buildChildrenByParent, collectSubtreeIds, compareCriticalItems, mergeSortedWarnings, packRankedContextItems, resolveContextTokenBudget, toContextPackingSummary, toContextRankingSummary, toContextFocusItem, } from "./context.js";
 import { runList } from "./list.js";
@@ -94,7 +95,7 @@ function buildRecommendationReasons(entry, statusRegistry, now, completedContain
         reasons.push(`advances ${item.parent.trim()}`);
     }
     if (entry.unblocks.length > 0) {
-        reasons.push(`unblocks ${entry.unblocks.length} item(s): ${entry.unblocks.join(", ")}`);
+        reasons.push(`unblocks ${entry.unblocks.length} item(s)`);
     }
     return reasons;
 }
@@ -118,12 +119,12 @@ export const _testOnlyNextCommand = {
     resolveNextCallerAuthor: (options, settingsAuthor) => resolveNextCallerAuthor(options, settingsAuthor),
 };
 /** Separates human-gated decisions from autonomous agent work unless the caller explicitly opts into decision claims. */
-export function partitionDecisionEntries(ready, includeDecisions) {
-    const decisions = ready.filter((entry) => entry.item.type.trim().toLowerCase() === "decision");
+export function partitionDecisionEntries(ready, includeDecisions, typeRegistry) {
+    const decisions = ready.filter((entry) => resolveItemExecutionRole(entry.item.type, typeRegistry) === "human");
     return {
         agent: includeDecisions
             ? ready
-            : ready.filter((entry) => entry.item.type.trim().toLowerCase() !== "decision"),
+            : ready.filter((entry) => resolveItemExecutionRole(entry.item.type, typeRegistry) !== "human"),
         decisions: includeDecisions ? [] : decisions,
     };
 }
@@ -195,13 +196,17 @@ function buildNextRecommendation(params) {
         reasons: buildRecommendationReasons(params.projectedReady[0], params.statusRegistry, params.now, params.completedContainer),
     };
 }
-function buildNextSuggestions(recommended, blockedRows) {
+function buildNextSuggestions(recommended, blockedRows, gateCount) {
     if (recommended !== null) {
         return undefined;
     }
+    const gateGuidance = gateCount > 0
+        ? ["No executable recommendation: outcome gates require verification. Inspect gate_needed, or use pm next --include-gates to opt in."]
+        : [];
     if (blockedRows.length > 0) {
         const blockedWithReferences = blockedRows.find((item) => item.blockers.length > 0);
         return [
+            ...gateGuidance,
             blockedWithReferences
                 ? `${blockedRows.length} item(s) are blocked; unblock the top one by closing ${blockedWithReferences.blockers.map((blocker) => blocker.id).join(", ")}`
                 : `${blockedRows.length} item(s) are blocked; add blocker context or move the top item back to an active status`,
@@ -210,6 +215,7 @@ function buildNextSuggestions(recommended, blockedRows) {
         ];
     }
     return [
+        ...gateGuidance,
         'pm create --type Task --title "..." to add a new work item',
         "pm list --status in_progress to review work already underway",
         "pm context --depth deep for the full project snapshot",
@@ -271,7 +277,7 @@ async function finalizeNextResult(params) {
         params.result.ranking = toContextRankingSummary(params.readyRanking, params.featureStore);
         params.result.packing = toContextPackingSummary(params.packing);
     }
-    params.result.suggestions = buildNextSuggestions(params.recommended, params.blockedRows);
+    params.result.suggestions = buildNextSuggestions(params.recommended, params.blockedRows, params.gateCount);
     await attachNextUsageFeedback({
         result: params.result,
         pmRoot: params.pmRoot,
@@ -291,9 +297,9 @@ function filterCandidatesByParentScope(candidates, corpus, parentScope) {
     }
     return candidates.filter((item) => subtree.ids.has(item.id.trim().toLowerCase()));
 }
-async function rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now, callerAuthor, pmRoot, tokenBudget) {
+async function rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now, callerAuthor, pmRoot, tokenBudget, includeContainers) {
     const concreteReady = rankedReady.filter((entry) => !hasCompletedDescendants(entry.item, childrenByParent));
-    const structuralReady = concreteReady.length > 0 ? concreteReady : rankedReady;
+    const structuralReady = includeContainers || concreteReady.length === 0 ? rankedReady : concreteReady;
     const usage = await readContextUsageAffinity({
         pmRoot,
         author: callerAuthor,
@@ -316,7 +322,7 @@ async function rankReadyEntriesWithRelevance(rankedReady, childrenByParent, stat
     return {
         projectedReady,
         ranking,
-        completedContainer: concreteReady.length === 0,
+        completedContainer: concreteReady.length === 0 && !includeContainers,
         packing,
         featureStore,
     };
@@ -335,6 +341,7 @@ export async function runNext(options, global) {
     const settings = await readSettings(pmRoot);
     const callerAuthor = resolveNextCallerAuthor(options, settings.author_default);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
+    const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const now = nowIso();
     const limit = parseNextLimit(options.limit, "--limit", DEFAULT_NEXT_LIMIT);
     const tokenBudget = resolveContextTokenBudget(options.tokenBudget, Math.max(192, limit * 128));
@@ -350,16 +357,18 @@ export async function runNext(options, global) {
     const corpusList = await runList(undefined, { excludeTerminal: false, noTruncate: true }, global);
     const candidates = filterCandidatesByParentScope(candidatesList.items, corpusList.items, parentScope);
     const corpus = corpusList.items;
-    const report = computeActionabilityReport(candidates, corpus, statusRegistry);
+    const report = computeActionabilityReport(candidates, corpus, statusRegistry, typeRegistry);
     const childrenByParent = buildChildrenByParent(corpus);
-    const partitionedByDecision = partitionDecisionEntries(report.ready, options.includeDecisions === true);
-    const callerPartition = partitionCallerOwnedReady(partitionedByDecision.agent, settings.author_default, callerAuthor);
+    const selected = selectActionableEntries(report, statusRegistry, options, typeRegistry);
+    const callerPartition = partitionCallerOwnedReady(selected.ready, settings.author_default, callerAuthor);
     const rankedReady = rankNextReadyEntries(callerPartition.available, childrenByParent, statusRegistry);
     const rankedBlocked = [...report.blocked].sort((left, right) => compareCriticalItems(left.item, right.item, statusRegistry));
-    const { projectedReady, ranking: readyRanking, completedContainer, packing: readyPacking, featureStore, } = await rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now, callerAuthor, pmRoot, tokenBudget);
+    const { projectedReady, ranking: readyRanking, completedContainer, packing: readyPacking, featureStore, } = await rankReadyEntriesWithRelevance(rankedReady, childrenByParent, statusRegistry, now, callerAuthor, pmRoot, tokenBudget, options.includeContainers === true);
     const readyRows = projectedReady.map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
     const blockedRows = rankedBlocked.map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
-    const decisionRows = rankNextReadyEntries(partitionedByDecision.decisions, childrenByParent, statusRegistry).map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
+    const decisionRows = rankNextReadyEntries(selected.decisions, childrenByParent, statusRegistry).map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
+    const gateRows = rankNextReadyEntries(selected.gates, childrenByParent, statusRegistry).map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
+    const containerRows = rankNextReadyEntries(report.containers, childrenByParent, statusRegistry).map((entry, index) => toNextActionableItem(entry, statusRegistry, childrenByParent, index + 1));
     const recommended = buildNextRecommendation({
         projectedReady,
         readyRows,
@@ -367,13 +376,19 @@ export async function runNext(options, global) {
         now,
         completedContainer,
     });
-    const truncation = buildNextTruncation(decisionRows.length, callerPartition.held.length, limit);
+    const truncation = buildNextTruncation(decisionRows.length, callerPartition.held.length, limit) ?? {};
+    if (gateRows.length > limit)
+        truncation.gate_needed_total = gateRows.length;
+    if (containerRows.length > limit)
+        truncation.containers_total = containerRows.length;
     const result = {
         output_default: "toon",
         now,
         recommended,
         ready: readyRows.slice(1, limit + 1),
         decision_needed: decisionRows.slice(0, limit),
+        gate_needed: gateRows.slice(0, limit),
+        containers: containerRows.slice(0, limit),
         blocked: readyOnly ? [] : blockedRows.slice(0, blockedLimit),
         held_by_others: callerPartition.held.slice(0, limit),
         summary: {
@@ -384,6 +399,7 @@ export async function runNext(options, global) {
             candidates: report.active_count,
             containers: report.container_count,
             decision_needed: decisionRows.length,
+            gate_needed: gateRows.length,
             held_by_others: callerPartition.held.length,
         },
         filters: {
@@ -399,14 +415,17 @@ export async function runNext(options, global) {
             blocked_limit: blockedLimit,
             ready_only: readyOnly,
             include_decisions: options.includeDecisions === true,
+            include_gates: options.includeGates === true,
+            include_containers: options.includeContainers === true,
             token_budget: tokenBudget,
         },
-        truncation,
+        truncation: Object.keys(truncation).length > 0 ? truncation : undefined,
     };
     return finalizeNextResult({
         result,
         recommended,
         blockedRows,
+        gateCount: gateRows.length,
         candidatesWarnings: candidatesList.warnings,
         corpusWarnings: corpusList.warnings,
         readyRanking,
@@ -424,6 +443,10 @@ export async function runNext(options, global) {
  */
 export function renderNextMarkdown(result) {
     const lines = ["# pm next", "", ...renderNextSummaryLines(result)];
+    for (const [title, rows] of [["Gate verification needed", result.gate_needed], ["Containers", result.containers]]) {
+        if (rows && rows.length > 0)
+            lines.push(...renderNextSection(title, rows.map((item) => `- ${formatNextLine(item)}`), ""));
+    }
     lines.push(...renderNextSection("Recommended", renderNextRecommendedRows(result.recommended), "No ready work."));
     lines.push(...renderNextSection("Decision needed", 
     // `?? []` tolerates JSON payloads from pre-decision-queue builds (the
@@ -488,4 +511,4 @@ function formatNextLine(item) {
     return `${rankToken}${item.id} p${item.priority} ${item.status} ${item.type} deadline:${deadlineToken}${parentToken}${unblocksToken} ${item.title}`;
 }
 //# sourceMappingURL=next.js.map
-//# debugId=b0f3d72c-ff0b-59bb-a6bc-8476eb9fb6c1
+//# debugId=6035e85b-81ed-512e-b291-b0d86af1848b

package/dist/sdk/query.d.ts

@@ -13,6 +13,7 @@ export { CONTEXT_OUTPUT_VALUES, applyContextTagProjection, buildChildrenByParent
 export * from "./query/get.js";
 export * from "./query/history.js";
 export * from "./query/next.js";
+export * from "./actionability.js";
 export * from "./query/search-pagination.js";
 export * from "./query/search-rendering.js";
 export * from "./query/item-filter-options.js";
@@ -27,3 +28,5 @@ export * from "./context-signal-store.js";
 export * from "./context-usage.js";
 export * from "./workspace-memory.js";
 export * from "./duplicates.js";
+export { analyzeDuplicateItems, type DuplicateItemInput, type DuplicateItemsAnalysis } from "./similarity.js";
+export { measureItemMetadataReadWork, type ItemMetadataReadWork } from "../core/store/item-metadata-read-work.js";

package/dist/sdk/query.js

@@ -4,7 +4,7 @@
  * Provides focused read, search, pagination, and context-ranking primitives.
  */
 
-!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]="036baf5a-3ba9-55ea-a11b-d9e94a848b92")}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]="affe6060-5129-5914-9d4e-46c300d49080")}catch(e){}}();
 export * from "./query/list.js";
 export * from "./query/complete-list.js";
 export * from "./query/search.js";
@@ -15,6 +15,7 @@ export { CONTEXT_OUTPUT_VALUES, applyContextTagProjection, buildChildrenByParent
 export * from "./query/get.js";
 export * from "./query/history.js";
 export * from "./query/next.js";
+export * from "./actionability.js";
 export * from "./query/search-pagination.js";
 export * from "./query/search-rendering.js";
 export * from "./query/item-filter-options.js";
@@ -29,5 +30,7 @@ export * from "./context-signal-store.js";
 export * from "./context-usage.js";
 export * from "./workspace-memory.js";
 export * from "./duplicates.js";
+export { analyzeDuplicateItems } from "./similarity.js";
+export { measureItemMetadataReadWork } from "../core/store/item-metadata-read-work.js";
 //# sourceMappingURL=query.js.map
-//# debugId=036baf5a-3ba9-55ea-a11b-d9e94a848b92
+//# debugId=affe6060-5129-5914-9d4e-46c300d49080

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

@@ -5,7 +5,7 @@
  * budgets and resolvable references to item facts served by earlier reads.
  */
 
-!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]="642f6dec-c0b2-5377-a401-dfa4f8ef6a2a")}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]="bb73f77d-d372-5d68-8ef2-90b208129f21")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { mapReadOutputRows, readOutputRowCollections, } from "./read-output-rows.js";
@@ -119,7 +119,9 @@ function summarizeReadOutputSessionRows(result) {
                 continue;
             }
             const itemId = itemIdFromRow(row);
-            if (itemId !== undefined)
+            // Activity can contain workspace pseudo-identities. Preserve those rows
+            // in the response, but only carry ids the next invocation can consume.
+            if (itemId !== undefined && ITEM_ID_PATTERN.test(itemId))
                 deliveredIds.add(itemId);
         }
     }
@@ -204,4 +206,4 @@ export function readOutputSessionRemainingTokens(state) {
     return Math.max(0, state.token_budget - state.spent_tokens);
 }
 //# sourceMappingURL=read-output-session.js.map
-//# debugId=642f6dec-c0b2-5377-a401-dfa4f8ef6a2a
+//# debugId=bb73f77d-d372-5d68-8ef2-90b208129f21

package/dist/sdk/runtime-primitives.d.ts

@@ -34,7 +34,7 @@ export { isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, } f
 export { COMMON_MUTATION_COMMAND_OPTION_KEYS, type ItemTypeRegistry, type ResolvedItemTypeDefinition, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveTypeDefinition, resolveTypeName, validateTypeOptions, } from "../core/item/type-registry.js";
 export { resolveTypeSynonym } from "../core/item/type-synonyms.js";
 export { acquireLock } from "../core/lock/lock.js";
-export { printError, printResult, writeStdout } from "../core/output/output.js";
+export { printError, printResult, writeStderr, writeStdout } from "../core/output/output.js";
 export { renderRowsAsCsv, renderRowsAsTable } from "../core/output/tabular.js";
 export { parseLimit } from "../core/shared/numeric-parsers.js";
 export { resolveConfiguredPmPackageRoot, resolvePmCliVersion, resolvePmPackageRootFromModule, } from "../core/packages/root.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="aba5403c-0694-5c51-95a8-ae7e7575347b")}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]="619b20e3-78d9-55bd-9d2d-857a3bc1bee8")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -36,7 +36,7 @@ export { isTerminalStatus, normalizeStatusForRegistry, normalizeStatusInput, } f
 export { COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveTypeDefinition, resolveTypeName, validateTypeOptions, } from "../core/item/type-registry.js";
 export { resolveTypeSynonym } from "../core/item/type-synonyms.js";
 export { acquireLock } from "../core/lock/lock.js";
-export { printError, printResult, writeStdout } from "../core/output/output.js";
+export { printError, printResult, writeStderr, writeStdout } from "../core/output/output.js";
 export { renderRowsAsCsv, renderRowsAsTable } from "../core/output/tabular.js";
 export { parseLimit } from "../core/shared/numeric-parsers.js";
 export { resolveConfiguredPmPackageRoot, resolvePmCliVersion, resolvePmPackageRootFromModule, } from "../core/packages/root.js";
@@ -82,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=aba5403c-0694-5c51-95a8-ae7e7575347b
+//# debugId=619b20e3-78d9-55bd-9d2d-857a3bc1bee8

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="099c7cda-4a92-553c-ad60-00e185b5971b")}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]="422ff60b-97b1-5477-a7b8-ed4f983155e0")}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";
@@ -1770,11 +1770,13 @@ const SDK_ACTION_HANDLERS = {
         return runGet(id, ctx.global, applyContextIntentProjection("get", ctx.options, [id]));
     },
     search: runMcpSearchAction,
+    /** Normalize MCP duplicate controls before delegating to the shared SDK action. */
     duplicates: (ctx) => {
         const status = typeof ctx.options.status === "string"
             ? [ctx.options.status]
             : readStringArray(ctx.options.status);
         return runDuplicates(ctx.global, {
+            exhaustive: ctx.options.exhaustive === true,
             ...(status.length === 0 ? {} : { status }),
             since: readString(ctx.options, "since"),
             threshold: typeof ctx.options.threshold === "number"
@@ -1924,4 +1926,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=099c7cda-4a92-553c-ad60-00e185b5971b
+//# debugId=422ff60b-97b1-5477-a7b8-ed4f983155e0

package/dist/sdk/similarity.d.ts

@@ -1,3 +1,4 @@
+import { collectDuplicateCandidatePairs } from "./query/duplicate-candidates.js";
 import type { ItemMetadata } from "../types/index.js";
 import { type PreparedSimilarityText } from "./similarity-scoring.js";
 export { jaccardSimilarity, normalizeSimilarityText, prepareSimilarityText, scoreItemSimilarity, scorePreparedItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, type PreparedSimilarityText, } from "./similarity-scoring.js";
@@ -51,6 +52,8 @@ export interface SimilarItemsResult {
 }
 /** Query controls for one all-status duplicate-cluster sweep. */
 export interface FindDuplicateClustersOptions extends FindSimilarItemsOptions {
+    /** Compare every pair as an exact oracle; retains the declared safety bound. */
+    exhaustive?: boolean;
     /** Lifecycle statuses to include; omit to inspect every status. */
     statuses?: readonly string[];
     /** Inclusive ISO timestamp lower bound on item creation. */
@@ -97,6 +100,14 @@ export interface DuplicateClustersResult {
     cost: {
         /** Items retained after filters. */
         item_count: number;
+        /** Algorithm used to generate candidates before canonical scoring. */
+        algorithm: "prefix_exact" | "exhaustive";
+        /** Pairs in the exhaustive population, including pairs pruned without scoring. */
+        possible_pairs: number;
+        /** Safety ceiling, exceeded only by an explicit refusal. */
+        pair_limit: number;
+        /** Every qualifying pair is retained by candidate generation. */
+        recall_guarantee: "exact";
         /** Candidate pairs sharing at least one deterministic signal. */
         candidate_pairs: number;
         /** Candidate pairs scored. */
@@ -104,7 +115,7 @@ export interface DuplicateClustersResult {
     };
 }
 interface PreparedDuplicateItem {
-    item: ItemMetadata;
+    item: Pick<ItemMetadata, "id" | "title" | "status" | "type">;
     prepared: PreparedSimilarityText;
 }
 /** Create/copy governance envelope attached when likely duplicates exist. */
@@ -131,7 +142,6 @@ export interface SimilarityRecovery {
 }
 /** Render compact warning tokens shared by create and copy results. */
 export declare function similarityAdvisoryWarnings(advisory: SimilarityAdvisory | undefined): string[];
-declare function collectDuplicateCandidatePairs(items: PreparedDuplicateItem[], maxPairEvaluations?: number): Set<string>;
 /** Internal deterministic seams used to prove bounded batch behavior without building a million-pair fixture. */
 export declare const _testOnlySimilarity: {
     buildDuplicateClusters: typeof buildDuplicateClusters;
@@ -142,10 +152,21 @@ declare function createDuplicateUnionFind(size: number): {
     parent: number[];
     findRoot: (index: number) => number;
 };
+/** Group unioned endpoints and their scored evidence once, then deterministically rank and limit complete components. */
 declare function buildDuplicateClusters(items: PreparedDuplicateItem[], matches: DuplicateClusterMatch[], union: ReturnType<typeof createDuplicateUnionFind>, limit: number): DuplicateCluster[];
 /** Find likely existing duplicates through an index-first bounded read. */
 export declare function findSimilarItems(candidate: SimilarItemCandidate, options?: FindSimilarItemsOptions): Promise<SimilarItemsResult>;
-/** Find connected duplicate clusters with one metadata read and one prepared representation per item. */
+/** Minimal metadata accepted from package-owned or remote project stores. */
+export type DuplicateItemInput = Pick<ItemMetadata, "id" | "title" | "status" | "type">;
+/** Exact in-memory duplicate analysis, independent of a filesystem workspace. */
+export type DuplicateItemsAnalysis = Omit<DuplicateClustersResult, "source" | "filters">;
+/**
+ * Cluster caller-owned metadata using the same scorer and safety bounds as the CLI.
+ * Candidate filtering is lossless; exhaustive mode provides an independent pair
+ * population for recall checks. Inputs are copied, sorted and never mutated.
+ */
+export declare function analyzeDuplicateItems(input: readonly DuplicateItemInput[], options?: Pick<FindDuplicateClustersOptions, "threshold" | "limit" | "exhaustive">): DuplicateItemsAnalysis;
+/** Find connected duplicate clusters with one metadata read and shared package analysis. */
 export declare function findDuplicateClusters(options?: FindDuplicateClustersOptions): Promise<DuplicateClustersResult>;
 /** Apply off/advisory/strict mutation governance through the shared query. */
 export declare function evaluateSimilarityGovernance(candidate: SimilarItemCandidate, options: FindSimilarItemsOptions & {

package/dist/sdk/similarity.js

@@ -5,7 +5,7 @@
  * governance and package-owned duplicate analysis.
  */
 
-!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]="33a43890-abcf-58fc-bf9d-bf2619d4cf35")}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]="9baf5711-9796-57e8-99e5-8990fd481ef8")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
@@ -16,6 +16,7 @@ import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { readItemMetadataDerivedIndexState } from "../core/store/item-metadata-cache.js";
 import { querySimilarItemMetadataIndex } from "../core/store/item-metadata-query-index.js";
+import { collectDuplicateCandidatePairs, MAX_DUPLICATE_CANDIDATE_PAIRS } from "./query/duplicate-candidates.js";
 import { prepareSimilarityText, scoreItemSimilarity, scorePreparedItemSimilarity, tokenizeSimilarityText, } from "./similarity-scoring.js";
 export { jaccardSimilarity, normalizeSimilarityText, prepareSimilarityText, scoreItemSimilarity, scorePreparedItemSimilarity, tokenizeSimilarityText, } from "./similarity-scoring.js";
 const DEFAULT_SIMILARITY_LIMIT = 3;
@@ -23,7 +24,6 @@ const MAX_SIMILARITY_LIMIT = 20;
 const DEFAULT_SIMILARITY_THRESHOLD = 0.8;
 const DEFAULT_DUPLICATE_CLUSTER_LIMIT = 100;
 const MAX_DUPLICATE_CLUSTER_LIMIT = 1_000;
-const MAX_BATCH_PAIR_EVALUATIONS = 1_000_000;
 /** Render compact warning tokens shared by create and copy results. */
 export function similarityAdvisoryWarnings(advisory) {
     return advisory === undefined
@@ -80,7 +80,8 @@ function validateDuplicateClusterOptions(options) {
     }
     return { limit, since };
 }
-async function loadPreparedDuplicateItems(options, since) {
+/** Resolve registered statuses and load the metadata population before applying status and creation-time filters. */
+async function loadDuplicateItems(options, since) {
     const pmRoot = resolvePmRoot(options.cwd ?? process.cwd(), options.pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings);
@@ -111,43 +112,10 @@ async function loadPreparedDuplicateItems(options, since) {
     return {
         items: (await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema))
             .filter((item) => (!allowedStatuses || allowedStatuses.has(item.status)) &&
-            (!since || new Date(item.created_at).getTime() >= since.getTime()))
-            .sort((left, right) => left.id.localeCompare(right.id))
-            .map((item) => ({ item, prepared: prepareSimilarityText(item.title) })),
+            (!since || new Date(item.created_at).getTime() >= since.getTime())),
         statuses: effectiveStatuses,
     };
 }
-function collectDuplicateCandidatePairs(items, maxPairEvaluations = MAX_BATCH_PAIR_EVALUATIONS) {
-    const candidates = new Set();
-    const indexes = [
-        new Map(),
-        new Map(),
-        new Map(),
-    ];
-    for (const [index, entry] of items.entries()) {
-        const signals = [
-            [entry.prepared.normalized],
-            entry.prepared.issueCodes,
-            entry.prepared.tokens,
-        ];
-        for (const [signalKind, values] of signals.entries()) {
-            for (const value of values) {
-                const matches = indexes[signalKind].get(value) ?? [];
-                for (const other of matches)
-                    candidates.add(`${other}:${index}`);
-                if (candidates.size > maxPairEvaluations) {
-                    throw new PmCliError(`Duplicate sweep exceeded ${MAX_BATCH_PAIR_EVALUATIONS} candidate pairs; narrow it with statuses or since.`, EXIT_CODE.CONFLICT, {
-                        code: "duplicate_sweep_cost_limit",
-                        required: "Narrow the batch duplicate query until its deterministic candidate set fits the disclosed safety bound.",
-                    });
-                }
-                matches.push(index);
-                indexes[signalKind].set(value, matches);
-            }
-        }
-    }
-    return candidates;
-}
 /** Internal deterministic seams used to prove bounded batch behavior without building a million-pair fixture. */
 export const _testOnlySimilarity = {
     buildDuplicateClusters,
@@ -190,6 +158,7 @@ function scoreDuplicateCandidates(items, candidates, threshold, union) {
     }
     return matches;
 }
+/** Group unioned endpoints and their scored evidence once, then deterministically rank and limit complete components. */
 function buildDuplicateClusters(items, matches, union, limit) {
     const components = new Map();
     for (const index of items.keys()) {
@@ -198,12 +167,19 @@ function buildDuplicateClusters(items, matches, union, limit) {
         component.push(index);
         components.set(root, component);
     }
+    const rootsById = new Map(items.map(({ item }, index) => [item.id, union.findRoot(index)]));
+    const matchesByRoot = new Map();
+    for (const match of matches) {
+        // Scored matches have already joined both endpoints in the union above.
+        const root = rootsById.get(match.left_id);
+        const rows = matchesByRoot.get(root) ?? [];
+        rows.push(match);
+        matchesByRoot.set(root, rows);
+    }
     return [...components.values()]
         .filter((component) => component.length > 1)
         .map((component) => {
-        const ids = new Set(component.map((index) => items[index].item.id));
-        const clusterMatches = matches
-            .filter((match) => ids.has(match.left_id) && ids.has(match.right_id))
+        const clusterMatches = (matchesByRoot.get(union.findRoot(component[0])) ?? [])
             .sort((left, right) => right.score - left.score ||
             left.left_id.localeCompare(right.left_id) ||
             left.right_id.localeCompare(right.right_id));
@@ -272,15 +248,24 @@ export async function findSimilarItems(candidate, options = {}) {
         source: indexed ? "persistent_index" : "metadata_fallback",
     };
 }
-/** Find connected duplicate clusters with one metadata read and one prepared representation per item. */
-export async function findDuplicateClusters(options = {}) {
-    const { threshold } = validateSimilarityOptions({
-        ...options,
-        limit: undefined,
-    });
-    const { limit, since } = validateDuplicateClusterOptions(options);
-    const { items, statuses } = await loadPreparedDuplicateItems(options, since);
-    const candidates = collectDuplicateCandidatePairs(items);
+/**
+ * Cluster caller-owned metadata using the same scorer and safety bounds as the CLI.
+ * Candidate filtering is lossless; exhaustive mode provides an independent pair
+ * population for recall checks. Inputs are copied, sorted and never mutated.
+ */
+export function analyzeDuplicateItems(input, options = {}) {
+    const { threshold } = validateSimilarityOptions({ ...options, limit: undefined });
+    const { limit } = validateDuplicateClusterOptions(options);
+    const ids = new Set();
+    for (const item of input) {
+        if (!item.id.trim() || ids.has(item.id)) {
+            throw new PmCliError("Duplicate analysis requires unique non-empty item ids.", EXIT_CODE.USAGE);
+        }
+        ids.add(item.id);
+    }
+    const items = [...input].sort((left, right) => left.id.localeCompare(right.id))
+        .map((item) => ({ item, prepared: prepareSimilarityText(item.title) }));
+    const candidates = collectDuplicateCandidatePairs(items, MAX_DUPLICATE_CANDIDATE_PAIRS, threshold, options.exhaustive === true);
     const union = createDuplicateUnionFind(items.length);
     const matches = scoreDuplicateCandidates(items, candidates, threshold, union);
     const clusters = buildDuplicateClusters(items, matches, union, limit);
@@ -288,18 +273,28 @@ export async function findDuplicateClusters(options = {}) {
         clusters,
         count: clusters.length,
         threshold,
-        source: "metadata_scan",
-        filters: {
-            statuses: statuses ?? null,
-            since: options.since ?? null,
-        },
         cost: {
             item_count: items.length,
+            algorithm: options.exhaustive === true || threshold === 0 ? "exhaustive" : "prefix_exact",
+            possible_pairs: items.length * (items.length - 1) / 2,
+            pair_limit: MAX_DUPLICATE_CANDIDATE_PAIRS,
+            recall_guarantee: "exact",
             candidate_pairs: candidates.size,
             scored_pairs: candidates.size,
         },
     };
 }
+/** Find connected duplicate clusters with one metadata read and shared package analysis. */
+export async function findDuplicateClusters(options = {}) {
+    validateSimilarityOptions({ ...options, limit: undefined });
+    const { since } = validateDuplicateClusterOptions(options);
+    const { items, statuses } = await loadDuplicateItems(options, since);
+    return {
+        ...analyzeDuplicateItems(items, options),
+        source: "metadata_scan",
+        filters: { statuses: statuses ?? null, since: options.since ?? null },
+    };
+}
 /** Apply off/advisory/strict mutation governance through the shared query. */
 export async function evaluateSimilarityGovernance(candidate, options) {
     if (options.mode === "off")
@@ -329,4 +324,4 @@ export async function evaluateSimilarityGovernance(candidate, options) {
     return { mode: options.mode, bypassed, result, recovery };
 }
 //# sourceMappingURL=similarity.js.map
-//# debugId=33a43890-abcf-58fc-bf9d-bf2619d4cf35
+//# debugId=9baf5711-9796-57e8-99e5-8990fd481ef8

package/dist/types.d.ts

@@ -428,6 +428,8 @@ export interface ItemTypeDefinition {
     description?: string;
     /** Status assigned to newly created items of this type when `--status` is not provided. Falls back to the workflow's open status when unset or invalid. */
     default_status?: string;
+    /** Agent work can be dispatched automatically; human work needs a decision, and gates track outcomes. Omission inherits the built-in role or defaults custom types to agent work. */
+    execution_role?: "agent" | "human" | "gate";
     /** Value that configures or reports folder for this contract. */
     folder?: string;
     /** Value that configures or reports aliases for this contract. */

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4ee067ac-f28d-5411-9ac7-c92112384a64")}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]="8173bdb0-39c8-56c0-85c2-5c39f5c213cc")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=4ee067ac-f28d-5411-9ac7-c92112384a64
+//# debugId=8173bdb0-39c8-56c0-85c2-5c39f5c213cc