@unbrained/pm-cli 2026.8.7 → 2026.8.9

package/dist/sdk/index.js

@@ -4,11 +4,11 @@
  * 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]="346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1")}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]="ae84c7af-bfa7-577d-b9f3-2bd9450d5755")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
-export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
-export { acknowledgeUnknownAuthorHistoryEvents, inspectHistoryAuthorStream, scanHistoryAuthorAttribution, } from "./author-attribution.js";
+export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
+export { acknowledgeUnknownAuthorHistoryEvents, acknowledgeUnknownAuthorHistoryEventsFromTransport, inspectHistoryAuthorStream, parseUnknownAuthorHistoryEventCoordinates, resolveUnknownAuthorAcknowledgmentSelector, scanHistoryAuthorAttribution, } from "./author-attribution.js";
 export { BUILTIN_CORPUS_SHAPES, PM_CORPUS_SHAPE_SCHEMA, buildCorpusShapeItemPlan, createCorpusShapeMeasurement, defineCorpusShape, listBuiltinCorpusShapes, measureCorpusShapePlan, resolveBuiltinCorpusShape, } from "./corpus-shape.js";
 export * from "./core-governance.js";
 export { createPmCliProgram } from "./cli-program.js";
@@ -30,7 +30,7 @@ export { runEvent, runMeet, runRemind, } from "./scheduling-shortcuts.js";
 export { createExtensionCommandSdk } from "./extension-command-context.js";
 export { isRuntimeRecord } from "./runtime-input.js";
 export { resolveStartTaskInProgressStatus } from "./start-task-status.js";
-export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
+export { auditMergeAttributeFence, buildMergeAttributePatterns, findGitWorkspaceRoot, installMergeFence, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, resolveProjectMergeTypeFolders, runMergeInstall, } from "./merge/install.js";
 export { deriveSchemaEvolutionMigrationId, formatSchemaEvolutionMigrationHuman, planSchemaEvolutionMigration, runSchemaEvolutionMigration, } from "./schema-migration.js";
 export { runWithActiveExtensions, } from "./runtime.js";
 export { applyInvocationAuthorOverride } from "./invocation-author.js";
@@ -50,6 +50,10 @@ export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, coll
 export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
+export * from "./environment/project-runtime-compatibility.js";
+export * from "./environment/source-context.js";
+export * from "./environment/host-environment-errors.js";
+export * from "./cli-contracts/command-exit-contracts.js";
 export * from "./context-relevance.js";
 export * from "./context-intent-contracts.js";
 export * from "./context-intent-runtime.js";
@@ -137,4 +141,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=346cbfc0-a42a-5ae6-b95a-af3bd63fc6d1
+//# debugId=ae84c7af-bfa7-577d-b9f3-2bd9450d5755

package/dist/sdk/learnings.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { LogNote } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the learnings command options payload exchanged by command, SDK, and package integrations. */
 export interface LearningsCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -19,6 +20,8 @@ export interface LearningsCommandOptions {
     delete?: number;
     /** Value that configures or reports limit for this contract. */
     limit?: string;
+    /** Return complete learning history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -34,6 +37,18 @@ export interface LearningsResult {
     learnings: LogNote[];
     /** Value that configures or reports count for this contract. */
     count: number;
+    /** Total learning count after the mutation. */
+    total_count?: number;
+    /** Number of learning entries returned in this projection. */
+    returned_count?: number;
+    /** Whether additional stored learning entries were withheld. */
+    has_more?: boolean;
+    /** Applied read limit when one was requested. */
+    limit?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older learnings were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run learnings for the public runtime surface of this module. */
 export declare function runLearnings(id: string, options: LearningsCommandOptions, global: GlobalOptions): Promise<LearningsResult>;

package/dist/sdk/learnings.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="26e30c82-7d6d-51b9-909f-b779213846b1")}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]="93184f29-f215-5413-9628-fb5b34523995")}catch(e){}}();
 import { parseAnnotationTextInput, resolveAnnotationInput, runAnnotationCommand, } from "./annotations.js";
 /** Implements run learnings for the public runtime surface of this module. */
 export async function runLearnings(id, options, global) {
@@ -24,4 +24,4 @@ export async function runLearnings(id, options, global) {
     });
 }
 //# sourceMappingURL=learnings.js.map
-//# debugId=26e30c82-7d6d-51b9-909f-b779213846b1
+//# debugId=93184f29-f215-5413-9628-fb5b34523995

package/dist/sdk/lifecycle/close-many.d.ts

@@ -5,6 +5,7 @@
  */
 import { type GlobalOptions, readSettings } from "../runtime-primitives.js";
 import { type ListOptions } from "../query/list.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the close many command options payload exchanged by command, SDK, and package integrations. */
 export interface CloseManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -55,7 +56,7 @@ interface CloseManyApplyRow {
     error?: string;
 }
 /** Documents the close many result payload exchanged by command, SDK, and package integrations. */
-export interface CloseManyResult {
+export interface CloseManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */
@@ -97,6 +98,10 @@ export interface CloseManyResult {
     }>;
     /** Value that configures or reports ids for this contract. */
     ids: string[];
+    /** Explicitly requested --ids values that matched no selected item. */
+    unmatched_ids?: string[];
+    /** Number of explicitly requested --ids values that matched no selected item. */
+    unmatched_count?: number;
 }
 declare function hasCloseManyFilters(list: ListOptions | undefined, status: string | undefined): boolean;
 declare function hasCloseManyRollbackConflicts(list: ListOptions | undefined, status: string | undefined): boolean;

package/dist/sdk/lifecycle/close-many.js

@@ -4,12 +4,13 @@
  * Implements the pm close many 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]="1be4d7c4-3ede-59cc-8d70-df966a66e67e")}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]="4da07a98-855e-59cf-a6a4-2f59a8b3c0bd")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, resolveAuthor, nowIso, listAllItemMetadataLight, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList } from "../query/list.js";
 import { runRestore } from "./restore.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const CLOSE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const CLOSE_MANY_CHECKPOINT_SUBDIR = "close-many";
 const CLOSE_MANY_FILTER_GUIDANCE = [
@@ -139,6 +140,12 @@ async function runCloseManyRollback(params) {
     const restoreMessage = params.options.message ?? `Rollback close-many checkpoint ${checkpoint.id}`;
     const rollback = await restoreCheckpointItems(checkpoint.items, (id, targetUpdatedAt) => runRestore(id, targetUpdatedAt, { author: params.options.author, message: restoreMessage, force: true }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -266,6 +273,13 @@ async function buildCloseManyPlanContext(params) {
     const listed = await runList(params.options.status, activeListOptions(params.options.list), params.global);
     const { childrenByParent, parentByChild } = await buildActiveChildrenByParent(params.pmRoot, params.settings);
     const matched = sortCloseManyMatchedItems(listed.items, parentByChild);
+    const requestedIds = [
+        ...new Set(String(params.options.list?.ids ?? "")
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0)),
+    ];
+    const matchedIds = new Set(matched.map((item) => item.id));
     const closePlannedIds = resolveCloseManyPlannedIds(matched, statusRegistry, force);
     return {
         pmRoot: params.pmRoot,
@@ -276,11 +290,14 @@ async function buildCloseManyPlanContext(params) {
         force,
         listed,
         matched,
+        unmatchedIds: requestedIds.filter((id) => !matchedIds.has(id)),
         planRows: planCloseManyRows(matched, childrenByParent, closePlannedIds, statusRegistry, force),
     };
 }
 function buildCloseManyDryRunResult(context) {
     return {
+        outcome: "effect",
+        exit_code: EXIT_CODE.SUCCESS,
         mode: "dry_run",
         matched_count: context.matched.length,
         dry_run: true,
@@ -291,6 +308,12 @@ function buildCloseManyDryRunResult(context) {
             : {}),
         item_plans: context.planRows,
         ids: [],
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 async function resolveCloseManyCheckpointInfo(params) {
@@ -362,7 +385,16 @@ export async function runCloseMany(options, global) {
         closeOptions,
         global,
     });
+    const closedCount = rows.filter((row) => row.status === "closed").length;
+    const skippedCount = rows.filter((row) => row.status === "skipped").length;
+    const failedCount = rows.filter((row) => row.status === "failed").length;
     return {
+        ...derivePmBulkMutationEffect({
+            applied: closedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: context.unmatchedIds.length,
+        }),
         mode: "apply",
         matched_count: context.matched.length,
         dry_run: false,
@@ -372,11 +404,17 @@ export async function runCloseMany(options, global) {
             ? { validate_close: context.validateCloseMode }
             : {}),
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        closed_count: rows.filter((row) => row.status === "closed").length,
-        skipped_count: rows.filter((row) => row.status === "skipped").length,
-        failed_count: rows.filter((row) => row.status === "failed").length,
+        closed_count: closedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows,
         ids: closedIds,
+        ...(context.unmatchedIds.length > 0
+            ? {
+                unmatched_ids: context.unmatchedIds,
+                unmatched_count: context.unmatchedIds.length,
+            }
+            : {}),
     };
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
@@ -390,4 +428,4 @@ export const _testOnly = {
     resolveReason,
 };
 //# sourceMappingURL=close-many.js.map
-//# debugId=1be4d7c4-3ede-59cc-8d70-df966a66e67e
+//# debugId=4da07a98-855e-59cf-a6a4-2f59a8b3c0bd

package/dist/sdk/lifecycle/close.js

@@ -4,9 +4,9 @@
  * Implements the pm close 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]="7d90aefe-43ba-5b24-8982-07e37e8d46a9")}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]="6e39a90e-8a26-5789-9de6-288900b6b418")}catch(e){}}();
 import { pathExists, toItemRecord, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveIsoOrRelative, shouldCompletePlanOnClose, getActiveExtensionRegistrations, } from "../runtime-primitives.js";
-import { collectBlockedByIds } from "../actionability.js";
+import { collectBlockedByIds, indexBlockedByIds, } from "../actionability.js";
 import { applyTerminalOrderingPolicy, requireTerminalReason, } from "../lifecycle-policy.js";
 import { renderPmCommand } from "../command-line.js";
 const CLOSE_VALIDATION_FIELDS = [
@@ -137,14 +137,19 @@ function findActiveChildIds(items, parentId, statusRegistry) {
         .sort((left, right) => left.localeCompare(right));
 }
 function findAutoUnblockCandidates(items, closedId, statusRegistry) {
-    const itemsById = new Map(items.map((item) => [item.id, item]));
+    const itemsById = new Map(items.map((item) => [item.id.trim().toLowerCase(), item]));
+    const blockerIdsByItem = indexBlockedByIds(items);
+    const normalizedClosedId = closedId.trim().toLowerCase();
     const blockedStatuses = statusRegistry.blocked_statuses;
     return items
         .filter((item) => blockedStatuses.has(item.status))
-        .map((item) => ({ item, blockerIds: collectBlockedByIds(item) }))
-        .filter(({ blockerIds }) => blockerIds.includes(closedId))
+        .map((item) => ({
+        item,
+        blockerIds: blockerIdsByItem.get(item.id.trim().toLowerCase()),
+    }))
+        .filter(({ blockerIds }) => blockerIds.includes(normalizedClosedId))
         .filter(({ blockerIds }) => blockerIds.every((blockerId) => {
-        if (blockerId === closedId) {
+        if (blockerId === normalizedClosedId) {
             return true;
         }
         const blocker = itemsById.get(blockerId);
@@ -171,7 +176,7 @@ async function autoUnblockResolvedDependents(pmRoot, settings, items, closedId,
                     const dependencies = document.metadata.dependencies ?? [];
                     /* c8 ignore stop */
                     const remainingDependencies = dependencies.filter((dependency) => {
-                        const dependencyId = dependency.id.trim();
+                        const dependencyId = dependency.id.trim().toLowerCase();
                         return (dependency.kind !== "blocked_by" ||
                             !candidate.blocker_ids.includes(dependencyId));
                     });
@@ -450,4 +455,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=7d90aefe-43ba-5b24-8982-07e37e8d46a9
+//# debugId=6e39a90e-8a26-5789-9de6-288900b6b418

package/dist/sdk/lifecycle/create.js

@@ -4,7 +4,7 @@
  * Implements the pm create 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]="93dc76a3-f205-5a44-85bd-5a6fad80c8d4")}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]="af455a7c-354f-54be-99e0-833c9f2710c5")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, resolvePriority, getFocusedItem, normalizeStatusInput, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { requireTerminalReasonWithRecovery } from "../lifecycle-policy.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
@@ -19,6 +19,7 @@ import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINIT
 import { ensureEnumValue } from "./recurrence-parsers.js";
 import { assertDependencyEdgesAllowed, assertValidBareDependencyFlagValue, } from "../dependency-flag-validation.js";
 import { normalizeDependencySeedId, normalizeDependencySourceKind, } from "../dependency-provenance.js";
+import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { parseEventEntries, parseReminderEntries, parseTypeOptionEntries, } from "./repeatable-metadata-parsers.js";
 import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, SCOPE_VALUES, } from "../../types/index.js";
 const CREATE_MODE_VALUES = ["strict", "progressive"];
@@ -188,17 +189,10 @@ function parseDependencies(raw, nowValue, prefix, fallbackAuthor) {
     });
     return { values, explicitEmpty: false };
 }
-const DEPENDENCY_KIND_INPUT_ALIASES = {
-    "blocked-by": "blocked_by",
-    depends_on: "blocked_by",
-    "depends-on": "blocked_by",
-};
 function normalizeDependencyKindInput(raw) {
-    if (typeof raw !== "string") {
-        return raw;
-    }
-    const alias = DEPENDENCY_KIND_INPUT_ALIASES[raw.toLowerCase()];
-    return alias ?? raw;
+    return typeof raw === "string"
+        ? (resolveCanonicalRelationshipKind(raw) ?? raw.trim())
+        : raw;
 }
 function looksLikeStructuredEntry(raw, keys) {
     if (raw.startsWith("```") || raw.includes("\n")) {
@@ -1841,4 +1835,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=93dc76a3-f205-5a44-85bd-5a6fad80c8d4
+//# debugId=af455a7c-354f-54be-99e0-833c9f2710c5

package/dist/sdk/lifecycle/plan.js

@@ -4,7 +4,7 @@
  * Implements the pm plan 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]="5d3c68a6-0b40-56b5-ae9e-776e1830ed3e")}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]="dc87393e-61e3-5d43-a756-d5f156faf29e")}catch(e){}}();
 import { pathExists, getActiveExtensionRegistrations, isTerminalStatus, resolveItemTypeRegistry, resolveRuntimeStatusRegistry, resolveTypeName, EXIT_CODE, PmCliError, splitCommaList, nowIso, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, isTerminalPlanMode, } from "../runtime-primitives.js";
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { runCreate, } from "./create.js";
@@ -522,7 +522,10 @@ function nextActionsFor(planId, plan) {
         tips.push(`pm plan approve ${planId} --message "ready to execute"`);
     }
     if (plan.steps_summary.completed === plan.steps_summary.total &&
-        plan.steps_summary.total > 0) {
+        plan.steps_summary.total > 0 &&
+        !isTerminalPlanMode(plan.mode) &&
+        plan.status !== "closed" &&
+        plan.status !== "canceled") {
         tips.push(`pm close ${planId} "plan complete"`);
     }
     return tips;
@@ -1579,4 +1582,4 @@ export const _testOnlyPlanCommand = {
     changedPlanMetadataFields,
 };
 //# sourceMappingURL=plan.js.map
-//# debugId=5d3c68a6-0b40-56b5-ae9e-776e1830ed3e
+//# debugId=dc87393e-61e3-5d43-a756-d5f156faf29e

package/dist/sdk/lifecycle/update-many.d.ts

@@ -8,6 +8,7 @@ import type { ItemStatus, PmSettings } from "../../types/index.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { type ListOptions, type ListedItem } from "../query/list.js";
 import { type UpdateCommandOptions } from "./update.js";
+import { type PmCommandEffectReceipt } from "../cli-contracts/command-exit-contracts.js";
 /** Documents the update many command options payload exchanged by command, SDK, and package integrations. */
 export interface UpdateManyCommandOptions {
     /** Lifecycle state reported for status. */
@@ -50,7 +51,7 @@ interface UpdateManyRollbackResultRow {
     error?: string;
 }
 /** Documents the update many result payload exchanged by command, SDK, and package integrations. */
-export interface UpdateManyResult {
+export interface UpdateManyResult extends PmCommandEffectReceipt {
     /** Value that configures or reports mode for this contract. */
     mode: "dry_run" | "apply" | "rollback";
     /** Number of matched entries represented by this result. */

package/dist/sdk/lifecycle/update-many.js

@@ -4,13 +4,14 @@
  * Implements the pm update many 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]="61fe3a97-39e6-53de-8663-8e70d931a2d4")}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]="67f8958d-60d5-5657-93ce-9803859acd9e")}catch(e){}}();
 import { pathExists, createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, toItemRecord, applyAcceptanceCriteriaMutations, applyTagRemovals, mergeAdditiveTags, parseOptionalNonNegativeInteger, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, resolveItemTypeRegistry, resolveTypeName, collectRuntimeUpdateFieldValues, buildInvalidTypeError, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, PmCliError, toErrorMessage, stableValueEquals, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { parseStatusFilterCsv } from "../../core/item/status-filter.js";
 import { hasListFilters } from "../query/list-filter-shared.js";
 import { runList, } from "../query/list.js";
 import { runRestore } from "./restore.js";
 import { runUpdate } from "./update.js";
+import { derivePmBulkMutationEffect, } from "../cli-contracts/command-exit-contracts.js";
 const UPDATE_MANY_CHECKPOINT_SCHEMA_VERSION = 1;
 const UPDATE_MANY_CHECKPOINT_SUBDIR = "update-many";
 const NON_MUTATION_UPDATE_OPTION_KEYS = new Set([
@@ -519,6 +520,12 @@ const runUpdateManyRollback = async (params) => {
         force: params.options.update?.force ?? true,
     }, params.global));
     return {
+        ...derivePmBulkMutationEffect({
+            applied: rollback.restored_ids.length,
+            skipped: 0,
+            failed: rollback.failed_count,
+            unmatched: 0,
+        }),
         mode: "rollback",
         matched_count: checkpoint.items.length,
         dry_run: false,
@@ -642,6 +649,8 @@ const buildUpdateManyPlan = async (params) => {
 };
 /** Builds the non-mutating preview response for a prepared update-many plan. */
 const buildUpdateManyDryRunResult = (plan) => ({
+    outcome: "effect",
+    exit_code: EXIT_CODE.SUCCESS,
     mode: "dry_run",
     matched_count: plan.listed.items.length,
     dry_run: true,
@@ -653,6 +662,12 @@ const buildUpdateManyDryRunResult = (plan) => ({
 });
 /** Builds the apply response for a plan whose rows are all already current. */
 const buildUpdateManyNoopResult = (plan) => ({
+    ...derivePmBulkMutationEffect({
+        applied: 0,
+        skipped: plan.listed.items.length,
+        failed: 0,
+        unmatched: plan.unmatchedIds?.length ?? 0,
+    }),
     mode: "apply",
     matched_count: plan.listed.items.length,
     dry_run: false,
@@ -742,16 +757,25 @@ const applyUpdateManyPlan = async (params) => {
     });
     /** Counts apply rows with one terminal status. */
     const countStatus = (status) => applied.rows.filter((row) => row.status === status).length;
+    const updatedCount = countStatus("updated");
+    const skippedCount = countStatus("skipped");
+    const failedCount = countStatus("failed");
     return {
+        ...derivePmBulkMutationEffect({
+            applied: updatedCount,
+            skipped: skippedCount,
+            failed: failedCount,
+            unmatched: params.plan.unmatchedIds?.length ?? 0,
+        }),
         mode: "apply",
         matched_count: params.plan.listed.items.length,
         dry_run: false,
         filters: params.plan.listed.filters,
         planned_update_options: params.plan.updateSummary,
         ...(checkpointInfo ? { checkpoint: checkpointInfo } : {}),
-        updated_count: countStatus("updated"),
-        skipped_count: countStatus("skipped"),
-        failed_count: countStatus("failed"),
+        updated_count: updatedCount,
+        skipped_count: skippedCount,
+        failed_count: failedCount,
         rows: applied.rows,
         ids: applied.updatedIds,
         ...buildUnmatchedIdFields(params.plan),
@@ -804,4 +828,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=61fe3a97-39e6-53de-8663-8e70d931a2d4
+//# debugId=67f8958d-60d5-5657-93ce-9803859acd9e

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]="ada579bd-134d-5201-9221-6ce39d282a37")}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]="233df258-47b7-571a-b445-9eab0c811702")}catch(e){}}();
 import { pathExists, COMMON_MUTATION_COMMAND_OPTION_KEYS, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, normalizeItemId, toItemRecord, buildInvalidTypeError, assertParentReferenceIsNotSelf, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, resolvePriority, normalizeStatusInput, isTerminalStatus, collectRuntimeUpdateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, describeAllowedTransitions, evaluateTransition, resolveTypeWorkflows, EXIT_CODE, PmCliError, stableValueEquals, resolveIsoOrRelative, getActiveExtensionRegistrations, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, buildItemNotFoundError, listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 import { runClose } from "./close.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
@@ -13,6 +13,7 @@ import { ensureEnumValue as ensureEnum } from "./recurrence-parsers.js";
 import { parseEventEntries, parseReminderEntries, parseTypeOptionEntries, } from "./repeatable-metadata-parsers.js";
 import { assertDependencyEdgesAllowed, assertValidBareDependencyFlagValue, } from "../dependency-flag-validation.js";
 import { normalizeDependencySeedId, normalizeDependencySourceKind, } from "../dependency-provenance.js";
+import { resolveCanonicalRelationshipKind } from "../relationships.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
 import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, } from "../../types/index.js";
 import { parseDocs, parseFiles, parseLogSeed, parseTests, requireStringOption, } from "./create.js";
@@ -386,25 +387,10 @@ function looksLikeStructuredDependencyEntry(raw) {
     // key is rejected rather than swallowed as a bare item id (GH-258).
     return looksLikeGenericKeyValueEntry(raw);
 }
-// pm-fl0c #4 (2026-05-28): `pm plan` accepts `depends_on` as a link kind
-// (`PLAN_STEP_LINK_KIND_VALUES`) but `pm update --dep kind=depends_on` rejected
-// it because `DEPENDENCY_KIND_VALUES` only lists `blocked_by`. The two terms
-// are semantically identical from this side ("X depends on Y" === "X blocked
-// by Y"), so we normalize input here rather than expanding the persisted enum
-// — the stored kind stays canonical (`blocked_by`) and downstream consumers
-// (closing logic, dependency graphs, blockers views) keep working unchanged.
-const DEPENDENCY_KIND_INPUT_ALIASES = {
-    "blocked-by": "blocked_by",
-    depends_on: "blocked_by",
-    "depends-on": "blocked_by",
-};
 function normalizeDependencyKindInput(raw) {
-    if (typeof raw !== "string") {
-        return raw;
-    }
-    const trimmed = raw.trim();
-    const alias = DEPENDENCY_KIND_INPUT_ALIASES[trimmed.toLowerCase()];
-    return alias ?? trimmed;
+    return typeof raw === "string"
+        ? (resolveCanonicalRelationshipKind(raw) ?? raw.trim())
+        : raw;
 }
 function parseDependencyAdditions(raw, prefix, nowIso, fallbackAuthor) {
     if (!raw) {
@@ -1874,4 +1860,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=ada579bd-134d-5201-9221-6ce39d282a37
+//# debugId=233df258-47b7-571a-b445-9eab0c811702

package/dist/sdk/merge/driver.d.ts

@@ -30,7 +30,7 @@ export interface MergeDriverResult {
     artifact: MergeDriverArtifact;
     /** Path the merged content was written to. */
     output_path: string;
-    /** Side unresolvable conflicts were resolved toward. */
+    /** Invocation-side preference retained for non-item artifact compatibility. */
     preferred: MergePreferredSide;
     /** Unresolvable conflict labels: metadata field names (item), dotted key paths (json). Empty for history merges. */
     conflicts: string[];
@@ -56,6 +56,7 @@ export interface MergeDriverResult {
     item?: {
         fields_from_theirs: string[];
         union_fields: string[];
+        conflict_resolution: "stable_value_order";
     };
     /** JSON-merge key accounting; present only for the json artifact. */
     json?: {

package/dist/sdk/merge/driver.js

@@ -9,7 +9,7 @@
  * merge never corrupts tracker storage the way raw conflict markers do.
  */
 
-!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]="182fee45-4de8-502d-8aec-84b5b8e4aecb")}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]="e739a603-35c5-5df9-8d4b-3bbc0fe3e4fd")}catch(e){}}();
 import { readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
@@ -127,18 +127,21 @@ export async function runMergeDriver(options, global) {
             schema: settings?.schema,
             extensionFieldNames: collectRegisteredItemFieldNames(getActiveExtensionRegistrations()),
             preferred,
+            conflictResolution: "stable_value_order",
         });
         merged = itemMerge.merged;
         conflicts.push(...itemMerge.conflict_fields);
         result.item = {
             fields_from_theirs: itemMerge.fields_from_theirs,
             union_fields: itemMerge.union_fields,
+            conflict_resolution: "stable_value_order",
         };
         if (options.itemPath !== undefined) {
             receiptInput = {
                 cwd: process.cwd(),
                 itemPath: options.itemPath,
                 preferred,
+                conflictResolution: "stable_value_order",
                 fieldsFromTheirs: itemMerge.fields_from_theirs,
                 unionFields: itemMerge.union_fields,
                 decisions: itemMerge.conflict_decisions,
@@ -167,10 +170,10 @@ export async function runMergeDriver(options, global) {
         const receiptGuidance = result.receipt === undefined
             ? 'Run "pm merge report" to inspect clone-local merge evidence.'
             : `Run "pm merge report" and correlate receipt ${result.receipt.receipt_id} with item ${result.receipt.item_id}; clone-local discarded values are never copied into this result.`;
-        guidance.push(`Both branches changed ${conflicts.join(", ")}; the ${preferred} value was kept. ${receiptGuidance} Review the merged file, re-apply the losing change if needed, then "git add" it.`);
+        guidance.push(`Both branches changed ${conflicts.join(", ")}; the item driver kept the direction-independent stable value. ${receiptGuidance} Review the merged file, re-apply the discarded change if needed, then "git add" it.`);
     }
     if (artifact === "history" && result.history?.reanchored) {
-        guidance.push('The merged history chain was re-anchored. Run "pm validate --check-history-drift" and "pm history-repair --all" after the merge to reconcile item state with merged history.');
+        guidance.push('The merged history chain was re-anchored. Run "pm merge reconcile --dry-run" to inspect the complete post-merge repair, then "pm merge reconcile" to apply it; use --force only after explicitly accepting reported discards.');
     }
     return {
         ok: conflicts.length === 0,
@@ -184,4 +187,4 @@ export async function runMergeDriver(options, global) {
     };
 }
 //# sourceMappingURL=driver.js.map
-//# debugId=182fee45-4de8-502d-8aec-84b5b8e4aecb
+//# debugId=e739a603-35c5-5df9-8d4b-3bbc0fe3e4fd

package/dist/sdk/merge/index.d.ts

@@ -9,5 +9,5 @@
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, type HistoryMergeResult, type HistoryMergeStrategy, type ItemDocumentMergeResult, type JsonDocumentMergeResult, type ItemMergeConflictDecision, type MergePreferredSide, type RelationshipStreamMergeResult, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, type MergeDecisionReceipt, type MergeDecisionReceiptSummary, type MergeReceiptReport, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, type MergeDriverArtifact, type MergeDriverOptions, type MergeDriverResult, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallResult, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
 export { runMergeReconcile, type MergeReconcileOptions, type MergeReconcileResult, } from "./reconcile.js";

package/dist/sdk/merge/index.js

@@ -7,11 +7,11 @@
  * this module so packages and hosts can reuse the same merge 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]="27725b9d-2a1d-54ae-8191-12ebace6ef6a")}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]="a8072065-092c-564b-a84f-cf687f795a92")}catch(e){}}();
 export { ITEM_LATEST_TIMESTAMP_FIELDS, ITEM_UNION_COLLECTION_FIELDS, mergeHistoryStreams, mergeItemDocuments, mergeJsonDocuments, mergeRelationshipEventStreams, } from "./three-way.js";
 export { listMergeReceipts, markMergeReceiptReconciled, runMergeReceiptReport, summarizeMergeReceipt, } from "./receipts.js";
 export { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, } from "./driver.js";
-export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, runMergeInstall, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=27725b9d-2a1d-54ae-8191-12ebace6ef6a
+//# debugId=a8072065-092c-564b-a84f-cf687f795a92