@unbrained/pm-cli 2026.9.5 → 2026.9.7

package/dist/sdk/query/duplicate-candidates.d.ts

@@ -0,0 +1,7 @@
+import type { PreparedSimilarityText } from "../similarity-scoring.js";
+/** Declared safety bound applies to retained pairs, never silently to recall. */
+export declare const MAX_DUPLICATE_CANDIDATE_PAIRS = 1000000;
+/** Generate every potentially qualifying pair once, with an explicit exhaustive oracle. */
+export declare function collectDuplicateCandidatePairs(items: readonly {
+    prepared: PreparedSimilarityText;
+}[], maxPairs?: number, threshold?: number, exhaustive?: boolean): Set<string>;

package/dist/sdk/query/duplicate-candidates.js

@@ -0,0 +1,71 @@
+/**
+ * @module sdk/query/duplicate-candidates
+ *
+ * Lossless prefix filtering for Jaccard joins. A globally ordered prefix of
+ * length n-ceil(threshold*n)+1 must intersect the corresponding prefix of
+ * every qualifying set. Exact titles and issue codes remain independent
+ * signals, including titles with no word tokens.
+ */
+
+!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]="d425cf45-5b62-5613-a5ce-78da6b0e201b")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
+/** Declared safety bound applies to retained pairs, never silently to recall. */
+export const MAX_DUPLICATE_CANDIDATE_PAIRS = 1_000_000;
+/** Generate every potentially qualifying pair once, with an explicit exhaustive oracle. */
+export function collectDuplicateCandidatePairs(items, maxPairs = MAX_DUPLICATE_CANDIDATE_PAIRS, threshold = 0.8, exhaustive = false) {
+    const candidates = new Set();
+    /** Deduplicate a candidate pair and refuse before publishing an over-budget result. */
+    const add = (left, right) => {
+        candidates.add(`${left}:${right}`);
+        if (candidates.size > maxPairs) {
+            throw new PmCliError(`Duplicate sweep exceeded ${maxPairs} candidate pairs; narrow it with statuses or since.`, EXIT_CODE.CONFLICT, { code: "duplicate_sweep_cost_limit", required: "Narrow the duplicate query or increase its similarity threshold. No partial result was returned." });
+        }
+    };
+    if (exhaustive || threshold === 0) {
+        for (let right = 0; right < items.length; right += 1) {
+            for (let left = 0; left < right; left += 1)
+                add(left, right);
+        }
+        return candidates;
+    }
+    const frequencies = new Map();
+    for (const { prepared } of items) {
+        for (const token of prepared.tokens)
+            frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    }
+    const exact = new Map();
+    const codes = new Map();
+    const prefixes = new Map();
+    for (const [right, { prepared }] of items.entries()) {
+        const tokens = [...prepared.tokens].sort((left, other) => frequencies.get(left) - frequencies.get(other) || left.localeCompare(other));
+        // An epsilon expands rather than shrinks the prefix at floating boundaries.
+        const prefixLength = tokens.length - Math.ceil(threshold * tokens.length - 1e-12) + 1;
+        const signals = [
+            { index: exact, keys: [prepared.normalized], lengthFilter: false },
+            { index: codes, keys: threshold <= 0.99 ? prepared.issueCodes : [], lengthFilter: false },
+            { index: prefixes, keys: tokens.length === 0 ? [""] : tokens.slice(0, prefixLength), lengthFilter: true },
+        ];
+        for (const signal of signals) {
+            appendPostingCandidates(items, right, signal, threshold, add);
+        }
+    }
+    return candidates;
+}
+/** Join one exact/code/prefix posting list, applying the Jaccard length bound only to tokens. */
+function appendPostingCandidates(items, right, signal, threshold, add) {
+    const rightLength = items[right].prepared.tokens.length;
+    for (const key of signal.keys) {
+        const posting = signal.index.get(key) ?? [];
+        for (const left of posting) {
+            const leftLength = items[left].prepared.tokens.length;
+            if (signal.lengthFilter && Math.min(leftLength, rightLength) / Math.max(leftLength, rightLength) + 1e-12 < threshold)
+                continue;
+            add(left, right);
+        }
+        posting.push(right);
+        signal.index.set(key, posting);
+    }
+}
+//# sourceMappingURL=duplicate-candidates.js.map
+//# debugId=d425cf45-5b62-5613-a5ce-78da6b0e201b

package/dist/sdk/query/get.js

@@ -4,7 +4,7 @@
  * 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]="16112e3d-b640-5114-a2c2-5effc655fe50")}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]="88732a1d-ae5a-5dfb-93d6-9659cb6f05c3")}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";
@@ -337,14 +337,14 @@ function attachGetLinked(result, context, fields, includeLinked) {
         docs: includeLinkedDocs ? (context.metadata.docs ?? []) : [],
     };
 }
-async function buildGetChildrenRollup(context, includeChildren, includeEmpty, includeSample) {
+/** Enumerate hierarchy metadata only when the caller explicitly requested a child rollup. */
+async function buildGetChildrenRollup(context, includeChildren) {
     if (!includeChildren) {
         return undefined;
     }
     const statusRegistry = resolveRuntimeStatusRegistry(context.settings.schema);
     const corpus = await listAllItemMetadataLight(context.pmRoot, context.settings.item_format, context.typeToFolder, undefined, context.settings.schema);
-    const rollup = buildItemChildrenRollup(context.locatedId, corpus, statusRegistry, includeSample ? undefined : 0);
-    return rollup.count > 0 || includeEmpty ? rollup : undefined;
+    return buildItemChildrenRollup(context.locatedId, corpus, statusRegistry);
 }
 function attachGetSchedule(result, context, fields, includeSchedule) {
     if (!includeSchedule) {
@@ -395,7 +395,7 @@ export async function runGet(id, global, options = {}) {
     const includeChildren = context.historical === undefined &&
         (projection.fieldProjection
             ? fieldsIncludeRoot(projection.fields, "children")
-            : projection.depth !== "brief" &&
+            : projection.depth === "deep" &&
                 shouldAutoIncludeGetChildren(context.metadata.type));
     const includeSchedule = projection.fieldProjection
         ? fieldsIncludeRoot(projection.fields, "schedule")
@@ -414,7 +414,7 @@ export async function runGet(id, global, options = {}) {
         result.claim_state = claimState;
     }
     attachGetSchedule(result, context, projection.fields, includeSchedule);
-    const children = await buildGetChildrenRollup(context, includeChildren, projection.fieldProjection, projection.fieldProjection || projection.depth === "deep");
+    const children = await buildGetChildrenRollup(context, includeChildren);
     if (children !== undefined) {
         result.children = children;
     }
@@ -448,4 +448,4 @@ export const _testOnlyGetCommand = {
     shouldAutoIncludeGetChildren,
 };
 //# sourceMappingURL=get.js.map
-//# debugId=16112e3d-b640-5114-a2c2-5effc655fe50
+//# debugId=88732a1d-ae5a-5dfb-93d6-9659cb6f05c3

package/dist/sdk/query.d.ts

@@ -28,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]="214c6bc1-313b-53c1-883a-d2d0536f8aea")}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";
@@ -30,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=214c6bc1-313b-53c1-883a-d2d0536f8aea
+//# 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.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/docs/AGENT_GUIDE.md

@@ -105,10 +105,22 @@ pm learnings <item-id> --add "Durable lesson for future work."
 pm test <item-id> --run --progress
 node scripts/run-tests.mjs coverage
 pm comments <item-id> "Evidence: linked test and coverage passed."
-pm close <item-id> "Acceptance criteria met; verification passed." --validate-close warn
+pm close <item-id> "Acceptance criteria met; verification passed." --resolution "Delivered behavior" --expected "Required outcome" --actual "Verified outcome" --validate-close warn
 pm release <item-id>
 ```
 
+If a warning close omitted evidence, use its `recovery.suggested_retry_args`
+to append an evidence update while preserving the original close event. See
+[Close Evidence Recovery](CLOSE_EVIDENCE_RECOVERY.md).
+
+For real subprocess tests, set `cwd`, `PM_PATH`, and `PM_GLOBAL_PATH` to the
+fixture's temporary workspace and trackers. This also isolates bootstrap and
+implicit discovery reads. Disable external probes with
+`PM_AGENT_PROBES=0` when testing deterministic process output.
+When testing conflicting ambient context, preserve that deliberate input in the
+fixture. CLI and MCP dispatch scope SDK identity signals to the resolved tracker;
+tests compare complete history bytes while the unrelated tracker's claims change.
+
 ## Token-Minimal Retrieval
 
 | Need                                 | Command                                                                                                                                                    |
@@ -181,6 +193,12 @@ Use the canonical [guide topic map](README.md#guide-topic-map) when local in-CLI
 
 ## Reviewed Delivery Closeout
 
+Before closing repository defects, set `escape_class` and structured
+`gate_evidence` through `pm update` as described in
+[Defect Evidence](DEFECT_RECURRENCE.md#defect-evidence-on-pm-items).
+Run `pnpm quality:defect-evidence` after the terminal transitions: a static
+gate run before closure cannot validate evidence required only for closed items.
+
 Treat PM evidence, item closure, and the generated changelog as part of the
 reviewed change. Add all evidence known before merge to the active branch,
 close and release the item there, regenerate `CHANGELOG.md`, and include those
@@ -219,7 +237,10 @@ positively and explain false or stale findings on their actual review surface.
 After each push, request the reviewers again and wait for terminal results;
 provider quota or skipped reviews are limitations, not approvals. Before merge,
 run `inventory` once more to catch new or edited feedback, and require all
-findings to have an explicit disposition.
+findings to have an explicit disposition. Compare each artifact's `revision`
+and pass it as `--revision` when acknowledging feedback, so edited bodies get
+fresh decisions and retrying a handled revision adds no duplicate reply.
+See [Review Loop](PR_REVIEW_LOOP.md) for the revision and reply contracts.
 
 ## Documentation Rules for Agents