@unbrained/pm-cli 2026.8.8 → 2026.8.10

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]="67f8958d-60d5-5657-93ce-9803859acd9e")}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]="0f91de58-2cbc-52ba-97ea-42482d0c6ce1")}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 { assertDependencyTargetsResolvable } from "../dependency-flag-validation.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 { assertUpdateMutationOptionCombinations, parseDependencyAdditions, 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";
@@ -20,6 +21,7 @@ const NON_MUTATION_UPDATE_OPTION_KEYS = new Set([
     "force",
     "ownershipMetadataBypass",
     "ownershipDependencyBypass",
+    "allowUnresolvedDeps",
 ]);
 const UPDATE_MANY_MUTATION_FLAG_GUIDANCE = [
     "--status",
@@ -379,19 +381,20 @@ const buildTagMutationPlan = (row, update) => {
 // --add-ac-only bulk update must NOT be treated as a no-op skip).
 const buildAcceptanceCriteriaMutationPlan = (row, update) => {
     const before = row.acceptance_criteria;
-    const base = update.acceptanceCriteria === undefined
-        ? before
-        : String(update.acceptanceCriteria).trim();
-    const mutation = applyAcceptanceCriteriaMutations(splitAcceptanceCriteria(base), update.addAc, update.removeAc);
-    const warnings = mutation.unmatchedRemovals.map((criterion) => `remove_ac_unmatched:${criterion}`);
+    const mutation = applyAcceptanceCriteriaMutations(splitAcceptanceCriteria(before), update.addAc, update.removeAc);
+    if (mutation.unmatchedRemovals.length > 0) {
+        throw new PmCliError(`Acceptance criteria removal did not match: ${mutation.unmatchedRemovals.join(", ")}`, EXIT_CODE.NOT_FOUND, {
+            code: "acceptance_criteria_remove_unmatched",
+            reason: "exact_match_not_found",
+            field: "acceptance_criteria",
+            unmatched: mutation.unmatchedRemovals,
+        });
+    }
     const after = mutation.criteria.join("; ");
-    if (areValuesEqual(before, after) || (before === undefined && after === "")) {
-        return { warnings };
+    if (areValuesEqual(typeof before === "string" ? before : "", after)) {
+        return undefined;
     }
-    return {
-        change: { field: "acceptance_criteria", before, after },
-        warnings,
-    };
+    return { field: "acceptance_criteria", before, after };
 };
 /** Adds changed scalar options to a planned item diff. */
 const appendScalarMutationPlans = (changes, row, update) => {
@@ -431,7 +434,6 @@ const appendUnsetMutationPlans = (changes, row, unset) => {
 const buildPlannedItemDiff = (item, runtimeFieldRegistry, update = {}) => {
     const row = toItemRecord(item);
     const changes = [];
-    const warnings = [];
     const tagPlan = buildTagMutationPlan(row, update);
     if (tagPlan) {
         changes.push(tagPlan);
@@ -439,13 +441,10 @@ const buildPlannedItemDiff = (item, runtimeFieldRegistry, update = {}) => {
     appendScalarMutationPlans(changes, row, update);
     if (updateArrayValueCount(update.addAc) > 0 ||
         updateArrayValueCount(update.removeAc) > 0) {
-        const composed = buildAcceptanceCriteriaMutationPlan(row, update);
-        const withoutAc = changes.filter((change) => change.field !== "acceptance_criteria");
-        changes.splice(0, changes.length, ...withoutAc);
-        if (composed.change !== undefined) {
-            changes.push(composed.change);
+        const acceptanceCriteriaChange = buildAcceptanceCriteriaMutationPlan(row, update);
+        if (acceptanceCriteriaChange !== undefined) {
+            changes.push(acceptanceCriteriaChange);
         }
-        warnings.push(...composed.warnings);
     }
     changes.push(...buildCollectionMutationPlans(row, update));
     appendRuntimeFieldMutationPlans(changes, row, update, runtimeFieldRegistry);
@@ -453,7 +452,6 @@ const buildPlannedItemDiff = (item, runtimeFieldRegistry, update = {}) => {
     return {
         id: item.id,
         changes,
-        ...(warnings.length > 0 ? { warnings } : {}),
     };
 };
 /** Normalizes an optional list status against the runtime schema. */
@@ -631,7 +629,15 @@ const buildUpdateManyPlan = async (params) => {
         includeBody: true,
         full: true,
     }, params.global);
-    const planned = listed.items.map((item) => buildPlannedItemDiff(item, params.runtime.runtimeFieldRegistry, params.options.update));
+    const planned = listed.items.map((item) => {
+        const diff = buildPlannedItemDiff(item, params.runtime.runtimeFieldRegistry, params.options.update);
+        return params.dependencyWarnings.length === 0
+            ? diff
+            : {
+                ...diff,
+                warnings: [...params.dependencyWarnings],
+            };
+    });
     const existenceItems = params.options.list?.ids == null
         ? []
         : (await runList(undefined, {
@@ -679,7 +685,6 @@ const buildUpdateManyNoopResult = (plan) => ({
     rows: plan.planned.map((row) => ({
         id: row.id,
         status: "skipped",
-        ...(row.warnings ? { warnings: row.warnings } : {}),
     })),
     ids: [],
     ...buildUnmatchedIdFields(plan),
@@ -689,15 +694,12 @@ const applyUpdateManyRows = async (params) => {
     const rows = [];
     const updatedIds = [];
     const updateMessage = params.options.update.message ?? `update-many apply ${params.checkpointId}`;
-    const plannedById = new Map(params.plans.map((row) => [row.id, row]));
     const actionableById = new Set(params.plans.filter((row) => row.changes.length > 0).map((row) => row.id));
     for (const item of params.items) {
         if (!actionableById.has(item.id)) {
-            const warnings = plannedById.get(item.id)?.warnings;
             rows.push({
                 id: item.id,
                 status: "skipped",
-                ...(warnings ? { warnings } : {}),
             });
             continue;
         }
@@ -800,11 +802,21 @@ export const runUpdateMany = async (options, global) => {
         throw new PmCliError(`No update-many mutation flags provided. Add at least one mutation flag (for example: ${UPDATE_MANY_MUTATION_FLAG_GUIDANCE}).`, EXIT_CODE.USAGE);
     }
     assertPlannedUpdateValuesValid(options.update, runtime.settings, runtime.statusRegistry, runtime.pmRoot);
+    assertUpdateMutationOptionCombinations(options.update);
+    const dependencyWarnings = await assertDependencyTargetsResolvable({
+        pmRoot: runtime.pmRoot,
+        dependencies: parseDependencyAdditions(options.update.dep, runtime.settings.id_prefix, nowIso(), resolveAuthor(options.update.author, runtime.settings.author_default)).additions,
+        idPrefix: runtime.settings.id_prefix,
+        itemFormat: runtime.settings.item_format,
+        typeToFolder: resolveItemTypeRegistry(runtime.settings, getActiveExtensionRegistrations()).type_to_folder,
+        allowUnresolved: options.update.allowUnresolvedDeps,
+    });
     const plan = await buildUpdateManyPlan({
         options,
         global,
         runtime,
         updateSummary,
+        dependencyWarnings,
     });
     return options.dryRun === true
         ? buildUpdateManyDryRunResult(plan)
@@ -828,4 +840,4 @@ export const _testOnlyUpdateManyCommand = {
     toComparablePreviewValue,
 };
 //# sourceMappingURL=update-many.js.map
-//# debugId=67f8958d-60d5-5657-93ce-9803859acd9e
+//# debugId=0f91de58-2cbc-52ba-97ea-42482d0c6ce1

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

@@ -40,6 +40,8 @@ export interface UpdateCommandOptions extends MutationMetadataCommandOptions, Sh
     force?: boolean;
     /** Permit an intentional unresolved parent reference under strict validation. */
     allowMissingParent?: boolean;
+    /** Explicitly permit unresolved local dependency targets with warning receipts. */
+    allowUnresolvedDeps?: boolean;
     /** Value that configures or reports dep remove for this contract. */
     depRemove?: string[];
     /** Value that configures or reports replace deps for this contract. */
@@ -96,7 +98,8 @@ interface DependencyRemovalSelector {
     kind?: (typeof DEPENDENCY_KIND_VALUES)[number];
     source_kind?: string;
 }
-declare function parseDependencyAdditions(raw: string[] | undefined, prefix: string, nowIso: string, fallbackAuthor: string): ParsedDependencyUpdates;
+/** Parse dependency additions into their canonical storage representation. */
+export declare function parseDependencyAdditions(raw: string[] | undefined, prefix: string, nowIso: string, fallbackAuthor: string): ParsedDependencyUpdates;
 declare function parseDependencyRemovals(raw: string[] | undefined, prefix: string): DependencyRemovalSelector[];
 declare function reconcileBlockedByDependency(current: Dependency[] | undefined, nextBlockedById: string | undefined, nowIsoValue: string, author: string): {
     dependencies: Dependency[] | undefined;
@@ -130,6 +133,8 @@ interface UpdateMutationContext {
     author: string;
     pmRoot: string;
 }
+/** Validate mutually exclusive and required update mutation option combinations. */
+export declare function assertUpdateMutationOptionCombinations(options: UpdateCommandOptions): void;
 type UpdateStatusMutationContext = Pick<UpdateMutationContext, "options" | "statusRegistry" | "clearItemMetadataKeys" | "nowIso">;
 declare function applyStatusAndCloseReasonMutations(document: ItemDocument, context: UpdateStatusMutationContext, previousStatusNormalized: string, changedFields: string[]): void;
 /** Implements run update for the public runtime surface of this module. */

package/dist/sdk/lifecycle/update.js

@@ -4,15 +4,16 @@
  * 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]="244583b8-2ffd-5da4-a4d3-46396fb354c0")}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";
 import { applyLegacyNoneCollectionNormalizers, createLegacyNoneCollectionNormalizers, assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken, } from "./legacy-none-tokens.js";
 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 { assertDependencyEdgesAllowed, assertDependencyTargetsResolvable, 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,27 +387,13 @@ 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) {
+/** Parse dependency additions into their canonical storage representation. */
+export function parseDependencyAdditions(raw, prefix, nowIso, fallbackAuthor) {
     if (!raw) {
         return { additions: [] };
     }
@@ -931,7 +918,20 @@ function validateLinkedArtifactReplacement(params) {
         throw new PmCliError(`${params.replaceFlag} cannot be combined with ${params.clearFlag}`, EXIT_CODE.USAGE);
     }
 }
-function validateReplaceOptions(options) {
+/** Validate mutually exclusive and required update mutation option combinations. */
+export function assertUpdateMutationOptionCombinations(options) {
+    const hasAdditiveAcceptanceCriteriaMutation = (options.addAc?.length ?? 0) > 0 || (options.removeAc?.length ?? 0) > 0;
+    if (options.acceptanceCriteria !== undefined &&
+        hasAdditiveAcceptanceCriteriaMutation) {
+        throw new PmCliError("Cannot combine --acceptance-criteria replacement with --add-ac or --remove-ac. Use --remove-ac and --add-ac together for an atomic one-entry repair.", EXIT_CODE.USAGE, {
+            code: "acceptance_criteria_mutation_conflict",
+            reason: "replacement_and_additive_mutation_combined",
+            nextSteps: [
+                "Use --acceptance-criteria alone to replace the complete list.",
+                "Use --remove-ac <old> --add-ac <new> to repair one criterion without replacing unrelated entries.",
+            ],
+        });
+    }
     if (options.replaceDeps === true &&
         (options.dep === undefined || options.dep.length === 0)) {
         throw new PmCliError("--replace-deps requires at least one --dep entry", EXIT_CODE.USAGE);
@@ -1458,7 +1458,7 @@ function applyTagsAndPlanningMutations(document, context, scalarMutationContext)
 // concurrent branch edits with disjoint additions merge instead of clobbering
 // the whole acceptance_criteria value (tag-API parity). Runs after the scalar
 // mutations so composition with a `--ac` replace uses the replaced base.
-function applyAcceptanceCriteriaAdditiveMutation(document, context, scalarMutationContext, warnings) {
+function applyAcceptanceCriteriaAdditiveMutation(document, context, scalarMutationContext) {
     const addValues = context.options.addAc;
     const removeValues = context.options.removeAc;
     if (!(Array.isArray(addValues) && addValues.length > 0) &&
@@ -1466,8 +1466,18 @@ function applyAcceptanceCriteriaAdditiveMutation(document, context, scalarMutati
         return;
     }
     const mutation = applyAcceptanceCriteriaMutations(splitAcceptanceCriteria(document.metadata.acceptance_criteria), addValues, removeValues);
-    for (const unmatched of mutation.unmatchedRemovals) {
-        warnings.push(`remove_ac_unmatched:${unmatched}`);
+    if (mutation.unmatchedRemovals.length > 0) {
+        throw new PmCliError(`Acceptance criteria removal did not match: ${mutation.unmatchedRemovals.join(", ")}`, EXIT_CODE.NOT_FOUND, {
+            code: "acceptance_criteria_remove_unmatched",
+            reason: "exact_match_not_found",
+            field: "acceptance_criteria",
+            unmatched: mutation.unmatchedRemovals,
+            why: "Lossless removal fails instead of silently applying the remaining mutations when an exact selector is wrong.",
+            nextSteps: [
+                "Read the current acceptance_criteria value and retry with the exact criterion text.",
+                "Use --acceptance-criteria alone only when replacing the complete list is intentional.",
+            ],
+        });
     }
     const nextValue = mutation.criteria.join("; ");
     if (document.metadata.acceptance_criteria === nextValue) {
@@ -1652,7 +1662,7 @@ function mutateUpdateDocument(document, context) {
     applyLogCollectionMutations(document, context, changedFields);
     applyEvidenceCollectionMutations(document, context, changedFields);
     applyTagsAndPlanningMutations(document, context, scalarMutationContext);
-    applyAcceptanceCriteriaAdditiveMutation(document, context, scalarMutationContext, warnings);
+    applyAcceptanceCriteriaAdditiveMutation(document, context, scalarMutationContext);
     applyOwnershipAndIssueMutations(document, context, scalarMutationContext, warnings);
     if (context.options.dep !== undefined ||
         context.options.depRemove !== undefined ||
@@ -1683,6 +1693,10 @@ function mutateUpdateDocument(document, context) {
     const actualChangedFields = [...new Set(changedFields)].filter((field) => field === "body"
         ? document.body !== beforeBody
         : !stableValueEquals(beforeMetadata[field], afterMetadata[field]));
+    if (context.options.acceptanceCriteria !== undefined &&
+        actualChangedFields.includes("acceptance_criteria")) {
+        warnings.push(`acceptance_criteria_replaced:${splitAcceptanceCriteria(beforeMetadata.acceptance_criteria).length}:${splitAcceptanceCriteria(afterMetadata.acceptance_criteria).length}`);
+    }
     return { changedFields: actualChangedFields, warnings };
 }
 /** Implements run update for the public runtime surface of this module. */
@@ -1715,7 +1729,7 @@ export async function runUpdate(id, options, global) {
     const unsetTargets = parseUpdateUnsetTargets(options.unset, runtimeFieldRegistry, extensionFieldNames);
     const clearOptionKeys = new Set(unsetTargets.optionKeys);
     const clearItemMetadataKeys = new Set(unsetTargets.metadataKeys);
-    validateReplaceOptions(options);
+    assertUpdateMutationOptionCombinations(options);
     applyClearCollectionDefinitions({
         definitions: buildClearCollectionDefinitions(options),
         options,
@@ -1729,6 +1743,14 @@ export async function runUpdate(id, options, global) {
     const nowValue = new Date();
     const nowIso = nowValue.toISOString();
     const dependencyUpdates = parseDependencyAdditions(options.dep, settings.id_prefix, nowIso, author);
+    const dependencyTargetWarnings = await assertDependencyTargetsResolvable({
+        pmRoot,
+        dependencies: dependencyUpdates.additions,
+        idPrefix: settings.id_prefix,
+        itemFormat: settings.item_format,
+        typeToFolder: typeRegistry.type_to_folder,
+        allowUnresolved: options.allowUnresolvedDeps,
+    });
     const dependencyRemovals = parseDependencyRemovals(options.depRemove, settings.id_prefix);
     const parsedCommentUpdates = parseLogSeed("--comment", options.comment, nowIso, author);
     const commentUpdates = options.ownershipMetadataBypass === true && parsedCommentUpdates.values
@@ -1851,6 +1873,7 @@ export async function runUpdate(id, options, global) {
         warnings: [
             ...workflowTransitionWarnings,
             ...parentReferenceWarnings,
+            ...dependencyTargetWarnings,
             ...orderingCycleWarnings,
             ...result.warnings,
         ],
@@ -1874,4 +1897,4 @@ export const _testOnlyUpdateCommand = {
     resolveRuntimeUnsetDefinition: (token, registry) => resolveRuntimeUnsetFieldDefinition(token, "update", registry),
 };
 //# sourceMappingURL=update.js.map
-//# debugId=ada579bd-134d-5201-9221-6ce39d282a37
+//# debugId=244583b8-2ffd-5da4-a4d3-46396fb354c0

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, resolveMergeInstallContext, runMergeInstall, type MergeFenceAuditResult, type MergeDriverConfigurationAuditResult, type MergeFenceRefreshOutcome, type MergeInstallOptions, type MergeInstallContextResolution, type MergeInstallResult, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_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]="a8072065-092c-564b-a84f-cf687f795a92")}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]="687855bf-7432-5691-a809-1f0406b5d8a8")}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, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
+export { auditMergeAttributeFence, auditMergeDriverConfiguration, buildMergeAttributePatterns, findGitWorkspaceRoot, PM_GITATTRIBUTES_END, PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_V2_END, PM_GITATTRIBUTES_V2_START, refreshMergeAttributeFenceIfInstalled, resolveMergeInstallContext, runMergeInstall, } from "./install.js";
 export { runMergeReconcile, } from "./reconcile.js";
 //# sourceMappingURL=index.js.map
-//# debugId=a8072065-092c-564b-a84f-cf687f795a92
+//# debugId=687855bf-7432-5691-a809-1f0406b5d8a8

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

@@ -5,6 +5,10 @@ import { resolveSourceContextWritePolicy } from "../environment/source-context.j
 export declare const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
 /** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
 export declare const PM_GITATTRIBUTES_END = "# pm-cli:merge-drivers:end";
+/** Opening marker for the versioned fence that older releases leave untouched. */
+export declare const PM_GITATTRIBUTES_V2_START = "# pm-cli:merge-drivers:v2:start";
+/** Closing marker for the versioned fence that older releases leave untouched. */
+export declare const PM_GITATTRIBUTES_V2_END = "# pm-cli:merge-drivers:v2:end";
 /** Documents the merge install options payload exchanged by command, SDK, and package integrations. */
 export interface MergeInstallOptions {
     /** Preview the `.gitattributes` and `git config` changes without writing anything. */

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]="94d2a7a8-ce00-5689-b2f6-3d4813234b55")}catch(e){}}();
 import { readFile, realpath, writeFile } from "node:fs/promises";
 import { execFile } from "node:child_process";
 import path from "node:path";
@@ -30,6 +30,10 @@ const execFileAsync = promisify(execFile);
 export const PM_GITATTRIBUTES_START = "# pm-cli:merge-drivers:start";
 /** Closing marker for the pm-owned merge-driver `.gitattributes` block. */
 export const PM_GITATTRIBUTES_END = "# pm-cli:merge-drivers:end";
+/** Opening marker for the versioned fence that older releases leave untouched. */
+export const PM_GITATTRIBUTES_V2_START = "# pm-cli:merge-drivers:v2:start";
+/** Closing marker for the versioned fence that older releases leave untouched. */
+export const PM_GITATTRIBUTES_V2_END = "# pm-cli:merge-drivers:v2:end";
 const MERGE_FENCE_LOCK_ID = "merge-fence";
 /**
  * Quote one argument for the shell used by Git merge-driver configuration.
@@ -235,6 +239,13 @@ export function buildMergeAttributePatterns(trackerRelativeRoot, typeFolders) {
     patterns.push(`${quoteGitAttributePattern(`${prefix}extensions/.managed-extensions.json`)} merge=pm-json`);
     return patterns;
 }
+function removeManagedBlock(content, startMarker, endMarker) {
+    const start = content.indexOf(startMarker);
+    const end = content.indexOf(endMarker);
+    return start >= 0 && end > start
+        ? `${content.slice(0, start)}${content.slice(end + endMarker.length)}`
+        : content.replace(startMarker, "").replace(endMarker, "");
+}
 async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
     const gitattributesPath = path.join(workspaceRoot, ".gitattributes");
     let current = "";
@@ -247,17 +258,11 @@ async function reconcileGitattributesBlock(workspaceRoot, patterns, dryRun) {
         }
     }
     const block = [
-        PM_GITATTRIBUTES_START,
+        PM_GITATTRIBUTES_V2_START,
         ...patterns,
-        PM_GITATTRIBUTES_END,
+        PM_GITATTRIBUTES_V2_END,
     ].join("\n");
-    const start = current.indexOf(PM_GITATTRIBUTES_START);
-    const end = current.indexOf(PM_GITATTRIBUTES_END);
-    const withoutManagedBlock = start >= 0 && end > start
-        ? `${current.slice(0, start)}${current.slice(end + PM_GITATTRIBUTES_END.length)}`
-        : current
-            .replace(PM_GITATTRIBUTES_START, "")
-            .replace(PM_GITATTRIBUTES_END, "");
+    const withoutManagedBlock = removeManagedBlock(removeManagedBlock(current, PM_GITATTRIBUTES_V2_START, PM_GITATTRIBUTES_V2_END), PM_GITATTRIBUTES_START, PM_GITATTRIBUTES_END);
     const prefix = withoutManagedBlock.trimEnd();
     const next = `${prefix.length > 0 ? `${prefix}\n\n` : ""}${block}\n`;
     if (next === current) {
@@ -290,7 +295,8 @@ export async function auditMergeAttributeFence(pmRoot, typeFolders) {
         const candidate = path.join(directory, ".gitattributes");
         try {
             const raw = await readFile(candidate, "utf8");
-            if (raw.includes(PM_GITATTRIBUTES_START)) {
+            if (raw.includes(PM_GITATTRIBUTES_V2_START) ||
+                raw.includes(PM_GITATTRIBUTES_START)) {
                 fenceDirectory = directory;
                 fenceContent = raw;
                 break;
@@ -314,11 +320,16 @@ export async function auditMergeAttributeFence(pmRoot, typeFolders) {
         };
     }
     const fencePath = path.join(fenceDirectory, ".gitattributes");
-    const start = fenceContent.indexOf(PM_GITATTRIBUTES_START);
-    const end = fenceContent.indexOf(PM_GITATTRIBUTES_END);
+    const usesV2 = fenceContent.includes(PM_GITATTRIBUTES_V2_START);
+    const startMarker = usesV2
+        ? PM_GITATTRIBUTES_V2_START
+        : PM_GITATTRIBUTES_START;
+    const endMarker = usesV2 ? PM_GITATTRIBUTES_V2_END : PM_GITATTRIBUTES_END;
+    const start = fenceContent.indexOf(startMarker);
+    const end = fenceContent.indexOf(endMarker);
     const committed = end > start
         ? fenceContent
-            .slice(start + PM_GITATTRIBUTES_START.length, end)
+            .slice(start + startMarker.length, end)
             .split("\n")
             .map((line) => line.trim())
             .filter((line) => line.length > 0)
@@ -408,7 +419,8 @@ export async function refreshMergeAttributeFenceIfInstalled(pmRoot) {
             }
             throw error;
         }
-        if (!current.includes(PM_GITATTRIBUTES_START)) {
+        if (!current.includes(PM_GITATTRIBUTES_V2_START) &&
+            !current.includes(PM_GITATTRIBUTES_START)) {
             return { status: "not_installed", path: gitattributesPath };
         }
         // Re-read after acquiring the dedicated fence lock so every concurrent
@@ -541,11 +553,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=94d2a7a8-ce00-5689-b2f6-3d4813234b55

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. */
@@ -23,6 +25,8 @@ export interface MergeDecisionReceipt {
     created_at: string;
     /** Reconciliation timestamp, when consumed. */
     reconciled_at?: string;
+    /** Whether decision values are recoverable locally or represented by hashes only. */
+    value_availability?: "clone_local" | "hash_only";
 }
 /** Privacy-safe receipt summary suitable for committed history context. */
 export interface MergeDecisionReceiptSummary {
@@ -40,6 +44,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 +71,24 @@ 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;
+    pmRoot?: string;
 }): 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. */