@unbrained/pm-cli 2026.8.31 → 2026.9.2

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/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="0823f083-1719-5ec2-9f7e-43bd86a2a3a2")}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]="4734edf6-c174-50d0-b4e9-1003bc8a20bf")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -2076,6 +2076,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_receipt_evidence_invalid",
         aliases: [],
     },
+    {
+        code: "merge_receipt_history_reference_missing",
+        meaning: "Merge receipt history reference missing condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["core/diagnostics/remediation.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_receipt_history_reference_missing",
+        aliases: [],
+    },
     {
         code: "merge_receipts_pending",
         meaning: "Merge receipts pending condition.",
@@ -2150,4 +2162,4 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
     },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=0823f083-1719-5ec2-9f7e-43bd86a2a3a2
+//# debugId=4734edf6-c174-50d0-b4e9-1003bc8a20bf

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health 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]="76693c03-9395-5bbf-bcc8-fa15e408f30f")}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]="f27cb24d-f2c8-5034-b655-84c577de7a16")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
@@ -28,6 +28,7 @@ import { EXIT_CODE, PM_CORE_REQUIRED_SUBDIRS, TYPE_TO_FOLDER, } from "../../core
 import { findFirstMergeConflictMarker } from "../../core/shared/conflict-markers.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
+import { sha256Hex } from "../../core/shared/serialization.js";
 import { nowIso } from "../../core/shared/time.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
@@ -46,7 +47,7 @@ import { buildCapabilityContractMetadata, buildRegistrationCollisionRemediation,
 import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
-import { inspectMergeReceiptEvidence, partitionMergeReceipts, } from "../merge/receipts.js";
+import { inspectMergeReceiptEvidence, isSafeReceiptId, partitionMergeReceipts, } from "../merge/receipts.js";
 import { runHistoryRepair } from "../history-repair.js";
 import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
 import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
@@ -278,11 +279,41 @@ async function scanItemIntegrity(pmRoot, typeToFolder, schema) {
     }
     return { paths, unreadable, conflictMarkers, parseFailures, formatVersions };
 }
+function mergeReceiptIdsFromHistoryEntry(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return [];
+    }
+    const context = value.context;
+    if (typeof context !== "object" ||
+        context === null ||
+        Array.isArray(context)) {
+        return [];
+    }
+    const merge = context.merge;
+    if (typeof merge !== "object" || merge === null || Array.isArray(merge)) {
+        return [];
+    }
+    const receipts = merge.receipts;
+    if (!Array.isArray(receipts))
+        return [];
+    return receipts.flatMap((receipt) => {
+        if (typeof receipt !== "object" ||
+            receipt === null ||
+            Array.isArray(receipt)) {
+            return [];
+        }
+        const receiptId = receipt.receipt_id;
+        return typeof receiptId === "string" && receiptId.length > 0
+            ? [receiptId]
+            : [];
+    });
+}
 async function scanHistoryIntegrity(pmRoot) {
     const historyDir = path.join(pmRoot, "history");
     const unreadable = [];
     const conflictMarkers = [];
     const invalidJson = [];
+    const mergeReceiptReferences = [];
     let files = [];
     try {
         files = (await fs.readdir(historyDir))
@@ -314,14 +345,25 @@ async function scanHistoryIntegrity(pmRoot) {
             if (!line.trim())
                 return;
             try {
-                JSON.parse(line);
+                const parsed = JSON.parse(line);
+                mergeReceiptReferences.push(...mergeReceiptIdsFromHistoryEntry(parsed).map((receiptId) => ({
+                    itemId,
+                    line: index + 1,
+                    receiptId,
+                })));
             }
             catch {
                 invalidJson.push({ id: itemId, line: index + 1 });
             }
         });
     }
-    return { files, unreadable, conflictMarkers, invalidJson };
+    return {
+        files,
+        unreadable,
+        conflictMarkers,
+        invalidJson,
+        mergeReceiptReferences,
+    };
 }
 function buildHierarchyIntegrityWarnings(analysis) {
     return [
@@ -336,10 +378,15 @@ function buildHierarchyIntegrityWarnings(analysis) {
             : `integrity_hierarchy_divergence:${finding.child_id}`),
     ];
 }
-function buildMergeReceiptEvidenceWarnings(invalidEvidenceCount) {
-    return invalidEvidenceCount === 0
-        ? []
-        : [`merge_receipt_evidence_invalid:${invalidEvidenceCount}`];
+function buildMergeReceiptEvidenceWarnings(params) {
+    const warnings = [];
+    if (params.invalidEvidenceCount > 0) {
+        warnings.push(`merge_receipt_evidence_invalid:${params.invalidEvidenceCount}`);
+    }
+    if (params.missingHistoryReferenceCount > 0) {
+        warnings.push(`merge_receipt_history_reference_missing:${params.missingHistoryReferenceCount}`);
+    }
+    return warnings;
 }
 async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
@@ -353,10 +400,21 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ? null
         : await auditMergeDriverConfiguration(gitWorkspaceRoot);
     const mergeReceiptEvidence = await inspectMergeReceiptEvidence(gitWorkspaceRoot ?? pmRoot, {
+        includeReconciled: true,
         includeLossless: true,
         pmRoot,
     });
-    const pendingMergeReceipts = mergeReceiptEvidence.receipts;
+    const availableMergeReceiptIds = new Set(mergeReceiptEvidence.receipts.map((receipt) => receipt.id));
+    const missingMergeReceiptReferences = historyScan.mergeReceiptReferences
+        .filter((reference) => !availableMergeReceiptIds.has(reference.receiptId))
+        .map((reference) => ({
+        item_id: reference.itemId,
+        history_line: reference.line,
+        ...(isSafeReceiptId(reference.receiptId)
+            ? { receipt_id: reference.receiptId }
+            : { receipt_reference_hash: sha256Hex(reference.receiptId) }),
+    }));
+    const pendingMergeReceipts = mergeReceiptEvidence.receipts.filter((receipt) => receipt.state === "pending");
     const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
     const mergeDriverInstallationMissing = mergeDriverAudit?.status === "missing" &&
         mergeDriverAudit.missing_keys.length === 5 &&
@@ -389,7 +447,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...(losslessMergeReceipts.length > 0
             ? [`merge_receipts_pending:${losslessMergeReceipts.length}`]
             : []),
-        ...buildMergeReceiptEvidenceWarnings(mergeReceiptEvidence.invalid_evidence_count),
+        ...buildMergeReceiptEvidenceWarnings({
+            invalidEvidenceCount: mergeReceiptEvidence.invalid_evidence_count,
+            missingHistoryReferenceCount: missingMergeReceiptReferences.length,
+        }),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
     const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
@@ -421,6 +482,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                     pending_merge_decisions: pendingMergeDecisions.length,
                     lossless_merge_receipts: losslessMergeReceipts.length,
                     invalid_merge_receipt_evidence: mergeReceiptEvidence.invalid_evidence_count,
+                    missing_merge_receipt_history_references: missingMergeReceiptReferences.length,
                 },
                 item_unreadable: itemScan.unreadable,
                 item_conflict_markers: itemScan.conflictMarkers,
@@ -452,6 +514,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
+                invalid_merge_receipt_evidence_details: mergeReceiptEvidence.invalid_evidence,
+                invalid_merge_receipt_evidence_details_truncated: mergeReceiptEvidence.invalid_evidence_truncated,
+                missing_merge_receipt_history_reference_details: missingMergeReceiptReferences.slice(0, HEALTH_WARNING_LIMIT),
+                missing_merge_receipt_history_reference_details_truncated: missingMergeReceiptReferences.length > HEALTH_WARNING_LIMIT,
             },
         },
         warnings: normalizedWarnings,
@@ -2309,4 +2375,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=76693c03-9395-5bbf-bcc8-fa15e408f30f
+//# debugId=f27cb24d-f2c8-5034-b655-84c577de7a16

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="cde10e58-cfeb-5718-a471-3e4acf46cfe7")}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]="0d466293-869d-54bb-b07d-facb3be51e8c")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -2053,6 +2053,8 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
                 ].sort((left, right) => left.localeCompare(right)),
                 lossless_merge_receipt_count: losslessMergeReceipts.length,
                 invalid_merge_receipt_evidence_count: mergeReceiptEvidence.invalid_evidence_count,
+                invalid_merge_receipt_evidence_details: mergeReceiptEvidence.invalid_evidence,
+                invalid_merge_receipt_evidence_details_truncated: mergeReceiptEvidence.invalid_evidence_truncated,
                 lossless_merge_receipt_items: [
                     ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
@@ -2273,4 +2275,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=cde10e58-cfeb-5718-a471-3e4acf46cfe7
+//# debugId=0d466293-869d-54bb-b07d-facb3be51e8c

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