@unbrained/pm-cli 2026.8.31 → 2026.9.1

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="41396cb5-7faf-5642-8746-8d94edb01d86")}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]="5ceccf7d-78cb-5750-8e4b-793efa6e716c")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -149,6 +149,60 @@ const RAW_TOOLS = [
             ...READ_OUTPUT_TOOL_PROPERTIES,
         }, ["action"]),
     },
+    {
+        name: "pm_discover",
+        description: "Discover the smallest relevant authorized pm tool catalog under an explicit token budget. " +
+            "Ranking is deterministic and returns public lexical, semantic, graph, permission, freshness, and usage signal explanations. " +
+            "Continue with next_cursor; set includeSchema=true only when complete input schemas are needed.",
+        inputSchema: objectSchema({
+            query: {
+                type: "string",
+                maxLength: 4096,
+                description: "Free-text capability intent. Empty text lists by stable policy order.",
+            },
+            family: {
+                type: "string",
+                enum: [
+                    "workspace",
+                    "intake",
+                    "context",
+                    "lifecycle",
+                    "evidence",
+                    "graph",
+                    "quality",
+                    "automation",
+                    "extensions",
+                    "internal",
+                ],
+                description: "Optional stable capability-family filter.",
+            },
+            tier: {
+                type: "string",
+                enum: ["core", "standard", "full"],
+                description: "Maximum command visibility tier included in results.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                maximum: 100,
+                description: "Maximum result rows; defaults to 10.",
+            },
+            cursor: {
+                type: "string",
+                minLength: 1,
+                maxLength: 4096,
+                description: "Opaque next_cursor from an equivalent discovery request.",
+            },
+            includeSchema: {
+                type: "boolean",
+                description: "Include complete tool input schemas; false by default.",
+            },
+            outputBudget: {
+                anyOf: [{ type: "integer", minimum: 128 }, { const: "unbounded" }],
+                description: "Estimated-token ceiling; defaults to 1200.",
+            },
+        }),
+    },
     {
         name: "pm_context",
         description: "Return the agent-oriented project context snapshot. " +
@@ -748,4 +802,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=41396cb5-7faf-5642-8746-8d94edb01d86
+//# debugId=5ceccf7d-78cb-5750-8e4b-793efa6e716c

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK 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]="d8f3f734-9adf-56f3-a5ba-c8b6407c4a89")}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]="f3f07ca8-7823-536d-b523-6d8f87c35f4a")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -176,6 +176,7 @@ export const PM_CORE_HELP_BUDGET = Object.freeze({
 /** Root options retained in the compact progressive-disclosure help screen. */
 export const PM_CORE_HELP_OPTION_FLAGS = Object.freeze([
     "-V, --version",
+    "--all",
     "--json",
     "--output-include <fields>",
     "--output-limit <count>",
@@ -277,6 +278,7 @@ export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
     pm_copy: "copy",
     pm_create: "create",
     pm_deps: "deps",
+    pm_discover: "help",
     pm_docs: "docs",
     pm_events: "history",
     pm_files: "files",
@@ -424,4 +426,4 @@ export function renderPmCapabilityRoutingMarkdown(contracts = PM_COMMAND_CAPABIL
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=d8f3f734-9adf-56f3-a5ba-c8b6407c4a89
+//# debugId=f3f07ca8-7823-536d-b523-6d8f87c35f4a

package/dist/sdk/history-read.js

@@ -7,13 +7,13 @@
  * systems without acquiring locks or appending history.
  */
 
-!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]="aca866d3-32b9-5212-bb4b-f1484e41bb27")}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]="f1ea4209-59d4-53f0-a8ea-2e060e385d14")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, replayHistoryToTarget, resolveHistoryTarget, } from "../core/history/projection.js";
 import { readHistoryEntries } from "../core/history/read.js";
-import { hashDocument, hashEmptyDocument, } from "../core/history/history.js";
-import { replayToCanonicalItemDocument, verifyHistoryChain, } from "../core/history/replay.js";
+import { hashDocument, hashDocumentVerificationCandidates, hashEmptyDocument, } from "../core/history/history.js";
+import { replayToCanonicalItemDocument, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -28,11 +28,19 @@ import { resolveHistorySubject } from "./history-redact.js";
  * document to compare.
  */
 export function verifyHistoryEntries(history, currentDocument) {
-    const verification = verifyHistoryChain(history);
+    const verification = verifyHistoryChainWithVersion(history);
     const latestAfterHash = history.length > 0
         ? history[history.length - 1].after_hash
         : hashEmptyDocument();
-    const currentItemHash = currentDocument === undefined ? undefined : hashDocument(currentDocument);
+    const currentItemHashCandidates = currentDocument === undefined ||
+        verification.item_hash_version === undefined
+        ? undefined
+        : hashDocumentVerificationCandidates(currentDocument, verification.item_hash_version);
+    const currentItemHash = currentDocument === undefined
+        ? undefined
+        : currentItemHashCandidates === undefined
+            ? hashDocument(currentDocument)
+            : currentItemHashCandidates[Math.max(0, currentItemHashCandidates.indexOf(latestAfterHash))];
     const currentMatchesLatest = currentItemHash === undefined
         ? undefined
         : currentItemHash === latestAfterHash;
@@ -83,4 +91,4 @@ export async function getItemAt(id, target, options = {}) {
 }
 export { applyHistoryPatch, ensureMaterializedHistoryTarget, extractPatchFailureContext, readHistoryEntries, replayHistoryToTarget, resolveHistoryTarget, };
 //# sourceMappingURL=history-read.js.map
-//# debugId=aca866d3-32b9-5212-bb4b-f1484e41bb27
+//# debugId=f1ea4209-59d4-53f0-a8ea-2e060e385d14

package/dist/sdk/history-repair.js

@@ -4,7 +4,7 @@
  * Implements the pm history repair 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]="04dbdc08-ad98-543f-96dc-fde635bae92e")}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]="151e5d26-d6f5-5fcf-84ab-ce89e2b7664e")}catch(e){}}();
 import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -12,7 +12,7 @@ import jsonPatch from "fast-json-patch";
 import { patchPathToChangedField } from "../core/history/history-diff.js";
 import { pathExists, readFileIfExists } from "../core/fs/fs-utils.js";
 import { executeHistoryRewrite, writeHistoryRawWithRollback, } from "../core/history/history-rewrite.js";
-import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHash, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
+import { historyEntriesToRaw, normalizeReplayPatchOps, reanchorHistoryEntries, replayHashVerificationCandidates, resolveHistoryRepairItemHashVersion, toReplayDocument, verifyHistoryChain, verifyHistoryChainWithVersion, } from "../core/history/replay.js";
 import { scanHistoryDrift } from "../core/history/drift-scan.js";
 import { invalidateHistoryDriftCache } from "../core/history/drift-cache.js";
 import { readHistoryEntries } from "../core/history/read.js";
@@ -287,11 +287,11 @@ async function loadHistoryRepairItemReplay(subject, settings, historyEntries, it
         };
     }
     const currentItemReplay = toReplayDocument(loadedItem.document);
-    const lastOriginalAfterHash = historyEntries[historyEntries.length - 1]?.after_hash;
+    const lastOriginalAfterHash = historyEntries[historyEntries.length - 1].after_hash;
     return {
         currentItemReplay,
         currentItemPath,
-        matchedChainBefore: replayHash(currentItemReplay, itemHashVersion) === lastOriginalAfterHash,
+        matchedChainBefore: replayHashVerificationCandidates(currentItemReplay, itemHashVersion).includes(lastOriginalAfterHash),
         currentItemRawBeforeLock: loadedItem.raw,
         loadedItem,
     };
@@ -312,6 +312,10 @@ function buildHistoryRepairEntries(params) {
     const afterReplay = params.reconcileNeeded && params.currentItemReplay
         ? params.currentItemReplay
         : params.finalReplay;
+    const beforeHashes = replayHashVerificationCandidates(params.finalReplay, params.itemHashVersion);
+    const previousAfterHash = params.reanchorEntries[params.reanchorEntries.length - 1].after_hash;
+    const semanticIndex = beforeHashes.indexOf(previousAfterHash);
+    const afterHashes = replayHashVerificationCandidates(afterReplay, params.itemHashVersion);
     rewrittenEntries.push({
         ts: nowIso(),
         author: params.author,
@@ -319,8 +323,8 @@ function buildHistoryRepairEntries(params) {
         patch: params.reconcileNeeded && params.currentItemReplay
             ? jsonPatch.compare(params.finalReplay, params.currentItemReplay)
             : [],
-        before_hash: replayHash(params.finalReplay, params.itemHashVersion),
-        after_hash: replayHash(afterReplay, params.itemHashVersion),
+        before_hash: beforeHashes[semanticIndex],
+        after_hash: afterHashes[semanticIndex],
         message: params.message,
         ...(params.explicitItemHashVersion
             ? { item_hash_version: params.itemHashVersion }
@@ -403,9 +407,12 @@ export async function runHistoryRepair(id, options, global) {
     const reanchor = reanchorHistoryEntries(provenanceNormalization.entries, itemHashVersion);
     const itemReplayContext = await loadHistoryRepairItemReplay(subject, settings, historyEntries, itemHashVersion);
     const finalReplay = reanchor.finalDocument;
-    const reconcileNeeded = itemReplayContext.currentItemReplay !== null &&
-        replayHash(finalReplay, itemHashVersion) !==
-            replayHash(itemReplayContext.currentItemReplay, itemHashVersion);
+    const finalReplayHashes = replayHashVerificationCandidates(finalReplay, itemHashVersion);
+    let reconcileNeeded = false;
+    if (itemReplayContext.currentItemReplay !== null) {
+        const currentItemReplayHashes = replayHashVerificationCandidates(itemReplayContext.currentItemReplay, itemHashVersion);
+        reconcileNeeded = !finalReplayHashes.some((hash, hashIndex) => hash === currentItemReplayHashes[hashIndex]);
+    }
     // GH-603: reconciling toward the on-disk item can silently overwrite the
     // replayed effect of other authors' events (classic after a lossy merge).
     // Surface exactly what is being discarded before any write happens.
@@ -591,4 +598,4 @@ export async function runHistoryRepairAll(options, global) {
     };
 }
 //# sourceMappingURL=history-repair.js.map
-//# debugId=04dbdc08-ad98-543f-96dc-fde635bae92e
+//# debugId=151e5d26-d6f5-5fcf-84ab-ce89e2b7664e

package/dist/sdk/index.d.ts

@@ -182,6 +182,7 @@ export { describeProfileComposition, describeProjectProfile, type ProjectProfile
 export { lintProjectProfile, PROFILE_LINT_CODES, PROFILE_LINT_DIMENSIONS, type ProfileLintCode, type ProfileLintDimension, type ProfileLintSeverity, type ProjectProfileLintFinding, type ProjectProfileLintReport, } from "../core/profile/profile-lint.js";
 export * from "./authoring.js";
 export * from "./governance.js";
+export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 export type { GlobalOptions } from "../core/shared/command-types.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="a903cbbb-e8b7-57d2-8f60-48885c6261a1")}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]="8a1a02de-32cb-5714-b950-6041ae8ce229")}catch(e){}}();
 export { PM_COMMAND_CAPABILITY_CONTRACTS, PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForFamily, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./mcp/protocol.js";
 export * from "./mcp/interactions.js";
@@ -173,7 +173,8 @@ export { describeProfileComposition, describeProjectProfile, } from "../core/pro
 export { lintProjectProfile, PROFILE_LINT_CODES, PROFILE_LINT_DIMENSIONS, } from "../core/profile/profile-lint.js";
 export * from "./authoring.js";
 export * from "./governance.js";
+export * from "./mcp/discovery.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=a903cbbb-e8b7-57d2-8f60-48885c6261a1
+//# debugId=8a1a02de-32cb-5714-b950-6041ae8ce229

package/dist/sdk/init-agent-guidance.js

@@ -4,7 +4,7 @@
  * Implements the pm init agent guidance 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]="e404796d-439b-5f4c-9330-5b12ff41d7b2")}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]="542cd5ac-e4a7-51fe-8521-d0bacd9e6a07")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline/promises";
@@ -96,10 +96,10 @@ function buildAgentGuidanceBlock(lineEnding, projectTestCommand = "<your project
         AGENT_GUIDANCE_START_MARKER,
         "## pm Workflow (Agent Quickstart)",
         "",
-        '- Orient before mutate: `pm context --limit 10`, `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`.',
+        '- Cold start with the measured canonical orientation: `pm context --limit 10 --for orient`; before item mutation, also run `pm search "<keywords>" --limit 10`, `pm list --status open --limit 20`, and `pm list --status in_progress --limit 20`.',
         "- Claim and execute: `pm claim <id>` then `pm update <id> --status in_progress`.",
         `- Link evidence while coding: \`pm files <id> --add ...\`, \`pm docs <id> --add ...\`, \`pm test <id> --add command="${projectTestCommand}"\`.`,
-        '- Verify and close: `pm test <id> --run --progress`, `pm close <id> "<evidence>" --validate-close warn`, `pm release <id>`.',
+        '- Verify and close: `pm test <id> --run --progress`, then atomically record closure evidence with `pm close <id> "<reason>" --resolution "<what changed>" --expected "<expected outcome>" --actual "<observed outcome>" --validate-close warn`, then `pm release <id>`.',
         "- Author identity is automatic for supported agent harnesses; use `--author` only for an explicit override.",
         "",
         AGENT_GUIDANCE_END_MARKER,
@@ -494,4 +494,4 @@ export async function runInitAgentGuidance(options) {
     };
 }
 //# sourceMappingURL=init-agent-guidance.js.map
-//# debugId=e404796d-439b-5f4c-9330-5b12ff41d7b2
+//# debugId=542cd5ac-e4a7-51fe-8521-d0bacd9e6a07

package/dist/sdk/lifecycle/update.js

@@ -4,7 +4,7 @@
  * Implements the pm update command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6865ca88-7ca1-52fd-86fb-2a3439abeafa")}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]="78f8b369-1802-555d-a8cc-0147c0d8fb08")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { resolveMutationStdinTokenFields } from "../../core/item/parse.js";
 import { COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, shouldResolveMutationStdinTokens, transferMutationStdinTokenPolicy, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, readLocatedItem, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
@@ -1273,6 +1273,25 @@ function applySimpleItemMutations(document, options, statusRegistry, changedFiel
     return (normalizeStatusInput(document.metadata.status, statusRegistry) ??
         document.metadata.status);
 }
+const TERMINAL_EVIDENCE_METADATA_KEYS = [
+    "closed_at",
+    "completed_at",
+    "close_reason",
+    "resolution",
+    "expected_result",
+    "actual_result",
+    "fixed_version",
+];
+/** Remove stale terminal evidence when work returns to an active lifecycle. */
+function clearTerminalEvidence(metadata, changedFields) {
+    for (const key of TERMINAL_EVIDENCE_METADATA_KEYS) {
+        if (metadata[key] === undefined) {
+            continue;
+        }
+        delete metadata[key];
+        changedFields.push(key);
+    }
+}
 function applyStatusMutation(document, context, statusInput, previousStatusNormalized, changedFields) {
     const status = parseStatus(statusInput, context.statusRegistry);
     document.metadata.status = status;
@@ -1286,14 +1305,8 @@ function applyStatusMutation(document, context, statusInput, previousStatusNorma
         return;
     }
     if (!isTerminalStatus(status, context.statusRegistry) &&
-        isTerminalStatus(previousStatusNormalized, context.statusRegistry) &&
-        document.metadata.closed_at !== undefined) {
-        delete document.metadata.closed_at;
-        changedFields.push("closed_at");
-        if (document.metadata.completed_at !== undefined) {
-            delete document.metadata.completed_at;
-            changedFields.push("completed_at");
-        }
+        isTerminalStatus(previousStatusNormalized, context.statusRegistry)) {
+        clearTerminalEvidence(document.metadata, changedFields);
     }
 }
 function applyStatusAndCompletionMutations(document, context, previousStatusNormalized, changedFields) {
@@ -2121,4 +2134,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=6865ca88-7ca1-52fd-86fb-2a3439abeafa
+//# debugId=78f8b369-1802-555d-a8cc-0147c0d8fb08

package/dist/sdk/mcp/discovery.d.ts

@@ -0,0 +1,152 @@
+import { type PmCommandCapabilityFamily, type PmCommandVisibilityTier, type PmMcpToolProfile } from "../agent-capability-contracts.js";
+/** Namespaced MCP extension that opts a client into progressive tool discovery. */
+export declare const PM_MCP_PROGRESSIVE_DISCOVERY_EXTENSION = "dev.unbrained.pm/progressive-tool-discovery";
+/** Versioned server capability advertised for progressive tool discovery. */
+export declare const PM_MCP_PROGRESSIVE_DISCOVERY_SERVER_CAPABILITY: Readonly<{
+    version: 1;
+    discoveryTool: "pm_discover";
+    canonicalResult: "structuredContent.result";
+    compatibilityText: "pointer";
+}>;
+/** Small stable tool catalog returned to clients that negotiate the extension. */
+export declare const PM_MCP_ENTRY_TOOL_NAMES: readonly string[];
+/** Ranking signals composed by the public discovery contract. */
+export type PmToolDiscoverySignalName = "lexical" | "semantic" | "graph" | "permission" | "freshness" | "usage";
+/** Optional host-owned signals supplied for one tool. */
+export interface PmToolDiscoverySignalInput {
+    /** Semantic relevance normalized to the inclusive range zero through one. */
+    semantic?: number;
+    /** Graph proximity normalized to the inclusive range zero through one. */
+    graph?: number;
+    /** Definition freshness normalized to the inclusive range zero through one. */
+    freshness?: number;
+    /** Historical selection usefulness normalized to the inclusive range zero through one. */
+    usage?: number;
+}
+/** One tool definition accepted by the SDK discovery engine. */
+export interface PmToolDiscoveryCandidate {
+    /** Stable callable tool name. */
+    name: string;
+    /** Agent-facing tool description. */
+    description: string;
+    /** JSON Schema supplied when callers request schema expansion. */
+    inputSchema: Record<string, unknown>;
+    /** Whether the current caller is authorized to invoke the tool. */
+    authorized?: boolean;
+    /** Optional host-owned ranking signals. */
+    signals?: PmToolDiscoverySignalInput;
+}
+/** Options controlling one progressive discovery page. */
+export interface PmToolDiscoveryOptions {
+    /** Free-text capability intent. Empty text lists by deterministic policy order. */
+    query?: string;
+    /** Restrict results to one stable capability family. */
+    family?: PmCommandCapabilityFamily;
+    /** Restrict results to tools visible at or below this tier. */
+    tier?: Exclude<PmCommandVisibilityTier, "internal">;
+    /** Maximum result rows, from one through one hundred. */
+    limit?: number;
+    /** Opaque continuation cursor from an equivalent discovery request. */
+    cursor?: string;
+    /** Include complete input schemas instead of the default compact projection. */
+    includeSchema?: boolean;
+    /** Estimated-token ceiling, or unbounded for the complete selected page. */
+    outputBudget?: number | "unbounded";
+    /** MCP profile that produced the authorized candidate catalog. */
+    profile?: PmMcpToolProfile;
+    /** Host-owned HMAC key of at least 32 bytes for restart-stable cursors. */
+    cursorIntegrityKey?: Uint8Array;
+}
+/** Applied score for one signal with explicit provenance. */
+export interface PmToolDiscoveryAppliedSignal {
+    /** Normalized signal value. */
+    value: number;
+    /** Public policy weight. */
+    weight: number;
+    /** Whether the signal was computed or supplied rather than defaulted. */
+    available: boolean;
+    /** Transparent source of the normalized value. */
+    source: "computed" | "host" | "authorization" | "unavailable";
+}
+/** One ranked discovery result. */
+export interface PmToolDiscoveryResultRow {
+    /** Stable callable tool name. */
+    name: string;
+    /** Agent-facing description. */
+    description: string;
+    /** Canonical CLI command backing the tool. */
+    command: string;
+    /** Minimum visibility tier inherited from the command contract. */
+    tier: PmCommandVisibilityTier;
+    /** Stable capability family inherited from the command contract. */
+    family: PmCommandCapabilityFamily;
+    /** Weighted aggregate score used for ordering. */
+    score: number;
+    /** Complete per-signal score explanation. */
+    signals: Readonly<Record<PmToolDiscoverySignalName, PmToolDiscoveryAppliedSignal>>;
+    /** Complete JSON Schema when explicitly requested. */
+    input_schema?: Record<string, unknown>;
+}
+/** Explicit receipt for information omitted from a discovery page. */
+export interface PmToolDiscoveryOmissionReceipt {
+    /** Whether any result rows or schemas were omitted. */
+    has_omissions: boolean;
+    /** Stable omitted field groups. */
+    omitted: Array<{
+        name: "input_schema" | "tools";
+        reason: "compact_projection" | "limit" | "token_budget";
+        restore_with: string;
+    }>;
+}
+/** Deterministic progressive tool discovery response. */
+export interface PmToolDiscoveryResult {
+    /** Stable result discriminator for model and host routing. */
+    result_type: "pm_tool_discovery";
+    /** Public contract revision. */
+    contract_version: 1;
+    /** Normalized query used by ranking and cursor binding. */
+    query: string;
+    /** MCP profile that produced the candidate catalog. */
+    profile: PmMcpToolProfile;
+    /** Ranked page of authorized tools. */
+    tools: PmToolDiscoveryResultRow[];
+    /** Total authorized rows after filters and before pagination. */
+    total: number;
+    /** Rows returned on this page. */
+    returned: number;
+    /** Whether a later ranked row remains. */
+    has_more: boolean;
+    /** Opaque continuation cursor bound to query, filters, and catalog. */
+    next_cursor?: string;
+    /** Exact estimated serialized result cost. */
+    token_cost: {
+        estimated_tokens: number;
+        budget: number | "unbounded";
+        within_budget: boolean;
+    };
+    /** Public ranking formula and weights. */
+    ranking_policy: {
+        version: 1;
+        formula: "weighted_sum_then_name";
+        weights: Readonly<Record<PmToolDiscoverySignalName, number>>;
+    };
+    /** Cache identity and invalidation contract for deterministic pages. */
+    cache: {
+        key: string;
+        ttl_ms: number;
+        scope: "private";
+        invalidates_on: readonly string[];
+    };
+    /** Explicit recovery for compacted fields and rows. */
+    omission_receipt: PmToolDiscoveryOmissionReceipt;
+}
+/** Parse untrusted adapter input without discarding malformed discovery values. */
+export declare function parsePmToolDiscoveryOptions(input: Record<string, unknown>): PmToolDiscoveryOptions;
+/**
+ * Rank and page an authorized MCP tool catalog under an explicit token budget.
+ *
+ * Cursors fail closed when the query, filters, schemas, authorization-filtered
+ * catalog, or ranking inputs change. Host signals override documented local
+ * fallbacks without changing the public formula or hiding signal provenance.
+ */
+export declare function discoverPmTools(candidates: readonly PmToolDiscoveryCandidate[], options?: PmToolDiscoveryOptions): PmToolDiscoveryResult;