@unbrained/pm-cli 2026.8.8 → 2026.8.9

package/dist/sdk/graph/run.js

@@ -11,7 +11,7 @@
  * queries in long-lived hosts are answered from the memoized snapshot.
  */
 
-!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]="0fbc54bf-3321-5c73-a351-5db01aab5544")}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]="ba8e7432-539e-55d3-b105-689db55d26b2")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -291,6 +291,7 @@ function runGraphAudit(invocation, isTerminal) {
         affected_subjects_by_severity: affectedBySeverity,
         affected_subjects_by_code: affectedByCode,
         profile: report.profile,
+        legacy_alias_counts: invocation.assembly.legacyAliasCounts,
         ...(invocation.summary ? {} : { findings: report.findings }),
     };
 }
@@ -713,4 +714,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=0fbc54bf-3321-5c73-a351-5db01aab5544
+//# debugId=ba8e7432-539e-55d3-b105-689db55d26b2

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.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/install.js

@@ -8,7 +8,7 @@
  * mutations refresh the fenced block automatically once it is installed.
  */
 
-!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]="fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158")}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]="cb6dc38e-b317-5739-83ff-cf459b8bb31e")}catch(e){}}();
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -541,11 +541,11 @@ export async function installMergeFence(options) {
         guidance: [
             "Commit .gitattributes so every branch and collaborator shares the merge mapping.",
             'git config is per-clone: each collaborator (and each fresh worktree/clone) runs "pm merge install" once.',
-            'After merging branches, run "pm validate" and, if history drift is reported, "pm history-repair --all" to reconcile item state with merged history.',
+            'After merging branches, run "pm merge reconcile --dry-run" to inspect the complete receipt and history repair, then apply "pm merge reconcile"; use --force only after explicitly accepting any discarded values.',
             "Custom item types registered later refresh this fence automatically (pm schema add-type/remove-type); rerun pm merge install only after out-of-band type-folder edits.",
         ],
         generated_at: nowIso(),
     };
 }
 //# sourceMappingURL=install.js.map
-//# debugId=fce8fc1d-b9ca-55bc-9c5a-f4f9728a7158
+//# debugId=cb6dc38e-b317-5739-83ff-cf459b8bb31e

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

@@ -11,6 +11,8 @@ export interface MergeDecisionReceipt {
     item_id: string;
     /** Preferred side used for scalar conflicts. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used by the item driver. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
     /** Fields selected cleanly from the other branch. */
     fields_from_theirs: string[];
     /** Collections combined from both branches. */
@@ -40,6 +42,8 @@ export interface MergeDecisionReceiptSummary {
     union_fields: string[];
     /** Preferred side used for scalar conflicts. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used by the item driver. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
     /** Hashes proving the retained and discarded values without publishing them. */
     decisions: Array<{
         field: string;
@@ -65,14 +69,23 @@ export declare function writeMergeReceipt(params: {
     cwd: string;
     itemPath: string;
     preferred: MergePreferredSide;
+    conflictResolution?: "preferred_side" | "stable_value_order";
     fieldsFromTheirs: string[];
     unionFields: string[];
     decisions: ItemMergeConflictDecision[];
 }): Promise<MergeDecisionReceipt | null>;
-/** Read all clone-local receipts, optionally including reconciled history. */
+/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export declare function listMergeReceipts(cwd: string, options?: {
     includeReconciled?: boolean;
+    includeLossless?: boolean;
 }): Promise<MergeDecisionReceipt[]>;
+/** Split merge provenance into receipts with discarded values and receipts whose composition was lossless. */
+export declare function partitionMergeReceipts(receipts: MergeDecisionReceipt[]): {
+    /** Receipts that require an explicit decision because at least one competing scalar value was discarded. */
+    pendingDecisions: MergeDecisionReceipt[];
+    /** Receipts that record provenance without a discarded competing scalar value. */
+    lossless: MergeDecisionReceipt[];
+};
 /** Mark a receipt as represented by a committed merge history event. */
 export declare function markMergeReceiptReconciled(cwd: string, receipt: MergeDecisionReceipt): Promise<void>;
 /** Report pending or historical clone-local merge decisions. */

package/dist/sdk/merge/receipts.js

@@ -7,7 +7,7 @@
  * value for the coordinator that performed the merge.
  */
 
-!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]="c4721ede-e557-5720-a9c2-4b2b344cc6cc")}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]="3ccde5c2-f743-52ac-a3fd-9590f720e1b3")}catch(e){}}();
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
@@ -19,7 +19,12 @@ import { nowIso } from "../../core/shared/time.js";
 const execFileAsync = promisify(execFile);
 async function resolveReceiptDirectory(cwd) {
     try {
-        const { stdout } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-path", "pm-merge-receipts"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
+        const { stdout } = await execFileAsync("git", [
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-path",
+            "pm-merge-receipts",
+        ], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000 });
         return stdout.trim();
     }
     catch {
@@ -39,6 +44,7 @@ export function summarizeMergeReceipt(receipt) {
         fields_from_theirs: receipt.fields_from_theirs,
         union_fields: receipt.union_fields,
         preferred: receipt.preferred,
+        conflict_resolution: receipt.conflict_resolution,
         decisions: receipt.decisions.map((decision) => ({
             field: decision.field,
             retained_hash: sha256Hex(stableStringify(decision.retained)),
@@ -65,6 +71,7 @@ export async function writeMergeReceipt(params) {
         item_path: itemPath.replaceAll("\\", "/"),
         item_id: itemId,
         preferred: params.preferred,
+        conflict_resolution: params.conflictResolution ?? "preferred_side",
         fields_from_theirs: [...params.fieldsFromTheirs],
         union_fields: [...params.unionFields],
         decisions: structuredClone(params.decisions),
@@ -75,7 +82,7 @@ export async function writeMergeReceipt(params) {
     await writeFileAtomic(path.join(directory, receiptFileName(receipt.id)), `${JSON.stringify(receipt, null, 2)}\n`);
     return receipt;
 }
-/** Read all clone-local receipts, optionally including reconciled history. */
+/** Read clone-local receipts with explicit reconciled/lossless classification controls. */
 export async function listMergeReceipts(cwd, options = {}) {
     const directory = await resolveReceiptDirectory(cwd);
     if (directory === null || !(await pathExists(directory))) {
@@ -95,9 +102,16 @@ export async function listMergeReceipts(cwd, options = {}) {
         }
         try {
             const parsed = JSON.parse(await readFile(path.join(directory, name), "utf8"));
-            if (parsed.version === 1 &&
-                (options.includeReconciled || parsed.state === "pending")) {
-                receipts.push(parsed);
+            const normalizedReceipt = {
+                ...parsed,
+                conflict_resolution: parsed.conflict_resolution ?? "preferred_side",
+            };
+            if (normalizedReceipt.version === 1 &&
+                (options.includeReconciled || normalizedReceipt.state === "pending") &&
+                (options.includeLossless !== false ||
+                    (Array.isArray(normalizedReceipt.decisions) &&
+                        normalizedReceipt.decisions.length > 0))) {
+                receipts.push(normalizedReceipt);
             }
         }
         catch {
@@ -107,6 +121,17 @@ export async function listMergeReceipts(cwd, options = {}) {
     }
     return receipts.sort((left, right) => left.created_at.localeCompare(right.created_at));
 }
+/** Split merge provenance into receipts with discarded values and receipts whose composition was lossless. */
+export function partitionMergeReceipts(receipts) {
+    const pendingDecisions = [];
+    const lossless = [];
+    for (const receipt of receipts) {
+        (Array.isArray(receipt.decisions) && receipt.decisions.length > 0
+            ? pendingDecisions
+            : lossless).push(receipt);
+    }
+    return { pendingDecisions, lossless };
+}
 /** Mark a receipt as represented by a committed merge history event. */
 export async function markMergeReceiptReconciled(cwd, receipt) {
     const directory = await resolveReceiptDirectory(cwd);
@@ -117,7 +142,10 @@ export async function markMergeReceiptReconciled(cwd, receipt) {
 }
 /** Report pending or historical clone-local merge decisions. */
 export async function runMergeReceiptReport(options) {
-    const receipts = await listMergeReceipts(options.cwd ?? process.cwd(), options);
+    const receipts = await listMergeReceipts(options.cwd ?? process.cwd(), {
+        ...options,
+        includeLossless: true,
+    });
     return {
         ok: true,
         count: receipts.length,
@@ -126,4 +154,4 @@ export async function runMergeReceiptReport(options) {
     };
 }
 //# sourceMappingURL=receipts.js.map
-//# debugId=c4721ede-e557-5720-a9c2-4b2b344cc6cc
+//# debugId=3ccde5c2-f743-52ac-a3fd-9590f720e1b3

package/dist/sdk/merge/reconcile.js

@@ -1,8 +1,10 @@
 
-!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]="b2f34565-7664-5612-815d-949b8b1d4f90")}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]="c5620467-6c8c-5702-b742-57fba9e302c5")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError } from "../../core/shared/errors.js";
 import { runHistoryRepair, runHistoryRepairAll, } from "../history-repair.js";
 import { runValidate } from "../governance/validate.js";
-import { listMergeReceipts, markMergeReceiptReconciled, summarizeMergeReceipt, } from "./receipts.js";
+import { listMergeReceipts, markMergeReceiptReconciled, partitionMergeReceipts, summarizeMergeReceipt, } from "./receipts.js";
 /**
  * Preview or apply post-merge history reconciliation and immediately validate
  * the two merge-critical invariants. The default remains explicit and safe:
@@ -11,7 +13,22 @@ import { listMergeReceipts, markMergeReceiptReconciled, summarizeMergeReceipt, }
  */
 export async function runMergeReconcile(options, global) {
     const dryRun = options.dryRun === true;
-    const pendingReceipts = await listMergeReceipts(process.cwd());
+    const pendingReceipts = await listMergeReceipts(process.cwd(), {
+        includeLossless: true,
+    });
+    const { pendingDecisions: discardedReceipts } = partitionMergeReceipts(pendingReceipts);
+    if (!dryRun && options.force !== true && discardedReceipts.length > 0) {
+        throw new PmCliError(`Merge reconciliation would accept ${discardedReceipts.length} receipt(s) containing discarded scalar values. Review pm merge report and rerun with --force only after deciding which values to retain or re-apply.`, EXIT_CODE.CONFLICT, {
+            code: "merge_reconcile_discards_require_acceptance",
+            required: "Explicitly review every discarded field before accepting reconciliation.",
+            nextSteps: discardedReceipts.map((receipt) => `Review receipt ${receipt.id} for ${receipt.item_id}: ${receipt.decisions
+                .map((decision) => decision.field)
+                .join(", ")}.`),
+            recovery: {
+                suggested_retry: "pm merge reconcile --dry-run",
+            },
+        });
+    }
     const receiptsByItem = pendingReceipts.reduce((groups, receipt) => {
         (groups[receipt.item_id] ??= []).push(receipt);
         return groups;
@@ -106,4 +123,4 @@ export async function runMergeReconcile(options, global) {
     };
 }
 //# sourceMappingURL=reconcile.js.map
-//# debugId=b2f34565-7664-5612-815d-949b8b1d4f90
+//# debugId=c5620467-6c8c-5702-b742-57fba9e302c5

package/dist/sdk/merge/three-way.d.ts

@@ -100,6 +100,8 @@ export interface ItemDocumentMergeResult {
     conflict_decisions: ItemMergeConflictDecision[];
     /** Which side unresolvable conflicts were resolved toward. */
     preferred: MergePreferredSide;
+    /** Scalar-conflict selection contract used for this merge. */
+    conflict_resolution: "preferred_side" | "stable_value_order";
 }
 /**
  * Field-aware three-way merge of one tracker item document. Commutative
@@ -107,8 +109,8 @@ export interface ItemDocumentMergeResult {
  * concurrent appends never conflict; `updated_at` resolves to the latest
  * timestamp so disjoint-field edits never collide on the shared freshness
  * scalar; every other metadata field and the body use classic three-way
- * resolution. Unresolvable both-sides-changed conflicts are resolved toward
- * the preferred side but reported in `conflict_fields`, and the merged output
+ * resolution. Unresolvable both-sides-changed conflicts use the configured
+ * scalar policy but remain reported in `conflict_fields`, and the merged output
  * is always canonically serialized — count-prefixed TOON array headers are
  * recomputed, so the hand-resolution corruption class (stale `notes[N]`
  * headers) cannot be produced by this merge.
@@ -116,6 +118,8 @@ export interface ItemDocumentMergeResult {
 export declare function mergeItemDocuments(baseRaw: string, oursRaw: string, theirsRaw: string, options?: ItemDocumentFormatOptions & {
     /** Side that wins unresolvable conflicts (default "ours"). */
     preferred?: MergePreferredSide;
+    /** Direction-independent scalar selection used by the Git driver. */
+    conflictResolution?: "preferred_side" | "stable_value_order";
 }): ItemDocumentMergeResult;
 /** Documents the JSON document merge result payload exchanged by command, SDK, and package integrations. */
 export interface JsonDocumentMergeResult {

package/dist/sdk/merge/three-way.js

@@ -9,7 +9,7 @@
  * definition for multi-branch agent workflows.
  */
 
-!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]="582576df-8dbe-5f93-890b-5d872669dfe8")}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]="f6f04eec-0698-5e5b-a40e-de3a4be89f95")}catch(e){}}();
 import { historyEntriesToRaw, reanchorHistoryEntries, } from "../../core/history/replay.js";
 import { canonicalDocument, parseItemDocument, serializeItemDocument, } from "../../core/item/item-format.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -339,6 +339,18 @@ function mergeScalarThreeWay(base, ours, theirs, preferred) {
         conflict: true,
     };
 }
+function mergeItemScalarThreeWay(base, ours, theirs, preferred, conflictResolution) {
+    const outcome = mergeScalarThreeWay(base, ours, theirs, preferred);
+    if (!outcome.conflict || conflictResolution === "preferred_side") {
+        return outcome;
+    }
+    const retainTheirs = stableStringify(theirs).localeCompare(stableStringify(ours)) < 0;
+    return {
+        value: retainTheirs ? theirs : ours,
+        from_theirs: retainTheirs,
+        conflict: true,
+    };
+}
 function toMetadataRecord(document) {
     return { ...document.metadata };
 }
@@ -350,7 +362,7 @@ function parseItemMergeSide(raw, label, options) {
         throw new PmCliError(`Item merge input (${label}) is not a readable item document: ${String(error)}`, EXIT_CODE.GENERIC_FAILURE);
     }
 }
-function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred) {
+function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution) {
     const unionFieldSet = new Set(ITEM_UNION_COLLECTION_FIELDS);
     const latestFieldSet = new Set(ITEM_LATEST_TIMESTAMP_FIELDS);
     const fieldNames = [
@@ -382,7 +394,7 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
             accumulator.merged[field] = latestTimestamp(oursValue, theirsValue);
             continue;
         }
-        const outcome = mergeScalarThreeWay(baseValue, oursValue, theirsValue, preferred);
+        const outcome = mergeItemScalarThreeWay(baseValue, oursValue, theirsValue, preferred, conflictResolution);
         if (outcome.value !== undefined) {
             accumulator.merged[field] = outcome.value;
         }
@@ -394,7 +406,7 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
                 ours: oursValue,
                 theirs: theirsValue,
                 retained: outcome.value,
-                discarded: preferred === "theirs" ? oursValue : theirsValue,
+                discarded: outcome.from_theirs ? oursValue : theirsValue,
             });
         }
         else if (outcome.from_theirs) {
@@ -409,14 +421,15 @@ function mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferre
  * concurrent appends never conflict; `updated_at` resolves to the latest
  * timestamp so disjoint-field edits never collide on the shared freshness
  * scalar; every other metadata field and the body use classic three-way
- * resolution. Unresolvable both-sides-changed conflicts are resolved toward
- * the preferred side but reported in `conflict_fields`, and the merged output
+ * resolution. Unresolvable both-sides-changed conflicts use the configured
+ * scalar policy but remain reported in `conflict_fields`, and the merged output
  * is always canonically serialized — count-prefixed TOON array headers are
  * recomputed, so the hand-resolution corruption class (stale `notes[N]`
  * headers) cannot be produced by this merge.
  */
 export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     const preferred = options.preferred ?? "ours";
+    const conflictResolution = options.conflictResolution ?? "preferred_side";
     // An empty base means both branches created the file independently
     // (add/add); three-way falls back to treating every differing field as an
     // ours/theirs decision, which the scalar resolver already models.
@@ -429,8 +442,8 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         : {};
     const oursRecord = toMetadataRecord(ours);
     const theirsRecord = toMetadataRecord(theirs);
-    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred);
-    const bodyOutcome = mergeScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred);
+    const { merged, conflictFields, fieldsFromTheirs, unionFields, conflictDecisions, } = mergeItemMetadataRecords(baseRecord, oursRecord, theirsRecord, preferred, conflictResolution);
+    const bodyOutcome = mergeItemScalarThreeWay(hasBase ? base.body : "", ours.body, theirs.body, preferred, conflictResolution);
     if (bodyOutcome.conflict) {
         conflictFields.push("body");
         conflictDecisions.push({
@@ -439,7 +452,7 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
             ours: ours.body,
             theirs: theirs.body,
             retained: bodyOutcome.value,
-            discarded: preferred === "theirs" ? ours.body : theirs.body,
+            discarded: bodyOutcome.from_theirs ? ours.body : theirs.body,
         });
     }
     else if (bodyOutcome.from_theirs) {
@@ -456,6 +469,7 @@ export function mergeItemDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
         union_fields: unionFields,
         conflict_decisions: conflictDecisions,
         preferred,
+        conflict_resolution: conflictResolution,
     };
 }
 function isPlainObject(value) {
@@ -611,4 +625,4 @@ export function mergeJsonDocuments(baseRaw, oursRaw, theirsRaw, options = {}) {
     };
 }
 //# sourceMappingURL=three-way.js.map
-//# debugId=582576df-8dbe-5f93-890b-5d872669dfe8
+//# debugId=f6f04eec-0698-5e5b-a40e-de3a4be89f95