@unbrained/pm-cli 2026.8.9 → 2026.8.11

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]="6e39a90e-8a26-5789-9de6-288900b6b418")}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]="83affe54-a56c-5d84-b6b0-9634d4238ff5")}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, indexBlockedByIds, } 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 = [
@@ -40,7 +40,7 @@ function findMissingCloseValidationFields(itemMetadata) {
     for (const field of CLOSE_VALIDATION_FIELDS) {
         const rawValue = itemMetadata[field.key];
         if (typeof rawValue !== "string" || rawValue.trim().length === 0) {
-            missing.push(field.label);
+            missing.push(field);
         }
     }
     return missing;
@@ -259,32 +259,34 @@ function applyDuplicateCloseMetadata(metadata, duplicateOf) {
     }
     return duplicateFallbackFields;
 }
-function collectCloseValidationWarnings(metadata, validateCloseMode, activeChildIds, closeReason) {
+function collectCloseValidationWarnings(metadata, validateCloseMode, activeChildIds, pmRoot) {
     const warnings = [];
     if (validateCloseMode !== "off") {
         const missingFields = findMissingCloseValidationFields(metadata);
         if (missingFields.length > 0) {
+            const missingLabels = missingFields.map((field) => field.label);
             if (validateCloseMode === "strict") {
-                const missingFlags = missingFields.map((field) => `--${field.replaceAll("_", "-")}`);
-                const retryTokens = [
-                    "close",
+                const missingFlags = missingFields.map((field) => `--${field.key.replaceAll("_", "-")}`);
+                const updateTokens = [
+                    "--pm-path",
+                    pmRoot,
+                    "update",
                     metadata.id,
-                    closeReason ?? "<reason>",
                     ...missingFlags.flatMap((flag) => [flag, "<value>"]),
                 ];
-                throw new PmCliError(`Cannot close item ${metadata.id}: missing ${missingFields.join(", ")}. Populate fields or use --validate-close warn.`, EXIT_CODE.USAGE, {
+                throw new PmCliError(`Cannot close item ${metadata.id}: missing ${missingLabels.join(", ")}. Populate fields or use --validate-close warn.`, EXIT_CODE.USAGE, {
                     code: "close_validation_missing_fields",
                     recovery: {
                         missing: missingFlags,
-                        suggested_retry: renderPmCommand(retryTokens),
+                        suggested_retry: renderPmCommand(updateTokens),
                     },
                     nextSteps: [
-                        "Use pm close with the missing closure fields populated.",
+                        "Run the suggested pm update, then retry the original pm close invocation.",
                         "Use --validate-close warn only when governance permits an evidenced exception.",
                     ],
                 });
             }
-            warnings.push(`close_validation_missing_fields:${metadata.id}:${missingFields.join(",")}`);
+            warnings.push(`close_validation_missing_fields:${metadata.id}:${missingLabels.join(",")}`);
         }
         if (activeChildIds.length > 0) {
             if (validateCloseMode === "strict") {
@@ -320,7 +322,7 @@ function mutateCloseMetadata(metadata, context) {
     }
     const inlineChangedFields = applyInlineCloseFields(metadata, context.options);
     const duplicateFallbackFields = applyDuplicateCloseMetadata(metadata, context.duplicateOf);
-    const mutationWarnings = collectCloseValidationWarnings(metadata, context.validateCloseMode, context.activeChildIds, context.closeReason);
+    const mutationWarnings = collectCloseValidationWarnings(metadata, context.validateCloseMode, context.activeChildIds, context.pmRoot);
     metadata.status = context.statusRegistry.close_status;
     metadata.closed_at = context.closedAt;
     const shouldWriteCompletedAt = context.options.completedAt !== undefined ||
@@ -428,6 +430,7 @@ export async function closeItem(id, closeReasonText, options, global) {
         force: options.force,
         mutate(document) {
             return mutateCloseMetadata(document.metadata, {
+                pmRoot,
                 statusRegistry,
                 force: options.force,
                 options,
@@ -455,4 +458,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=6e39a90e-8a26-5789-9de6-288900b6b418
+//# debugId=83affe54-a56c-5d84-b6b0-9634d4238ff5

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

@@ -34,6 +34,8 @@ export interface CreateCommandOptions extends MutationMetadataCommandOptions, Sh
     body?: string;
     /** Value that configures or reports allow missing parent for this contract. */
     allowMissingParent?: boolean;
+    /** Explicitly permit unresolved local dependency targets with warning receipts. */
+    allowUnresolvedDeps?: boolean;
     /** Value that configures or reports template for this contract. */
     template?: string;
     /** Creates mode using the validated operation inputs. */

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]="af455a7c-354f-54be-99e0-833c9f2710c5")}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]="ffa56c1a-d98c-566a-81c5-4ad5608aa26c")}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";
@@ -17,9 +17,10 @@ import { parseLinkedTestAssertionEqualsMap, parseLinkedTestAssertionGteMap, pars
 import { looksLikeStructuredLinkedTestEntry, normalizeStructuredLinkedTestEntry, } from "../test/entry.js";
 import { COMMON_UNSET_FIELD_DEFINITIONS_AFTER_AUTHOR, COMMON_UNSET_FIELD_DEFINITIONS_BEFORE_AUTHOR, parseCommandUnsetTargets, resolveRuntimeUnsetFieldDefinition, } from "./shared-unset-fields.js";
 import { ensureEnumValue } from "./recurrence-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 { supportsCreateExplicitEmpty } from "../agent/create-option-policy.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"];
@@ -515,7 +516,7 @@ function assertNoStrictRequiredOptionClears(requiredOptions, createMode, clearOp
     if (createMode !== "strict") {
         return;
     }
-    const strictRequiredClears = requiredOptions.filter((required) => clearOptionKeys.has(required));
+    const strictRequiredClears = requiredOptions.filter((required) => clearOptionKeys.has(required) && !supportsCreateExplicitEmpty(required));
     if (strictRequiredClears.length === 0) {
         return;
     }
@@ -613,6 +614,10 @@ function requireCreateOptionByType(typeDefinition, options, createMode, clearOpt
         if (optionKey === "status" && typeDefinition.default_status !== undefined) {
             return true;
         }
+        if (clearOptionKeys.has(optionKey) &&
+            supportsCreateExplicitEmpty(optionKey)) {
+            return true;
+        }
         return hasCreateOptionValue(optionLookup, optionKey);
     };
     const missingRequiredOptions = policyState.required.filter((required) => !satisfiesRequiredOption(required));
@@ -1030,6 +1035,7 @@ function collectTemplateCustomTypeOptions(typeDefinition, resolvedOptions) {
 /** Resolve the target item type and creation mode for `pm create`: merge any `--template` options, apply the governance default-type fallback, map a near-miss `--type` to its canonical synonym (never blocking), and derive the schedule preset and effective create mode. Returns the (possibly template-merged) options alongside the resolved type definition, canonical type name, schedule preset, and create mode. */
 async function resolveCreateTypeSelection(options, global, pmRoot, settings, typeRegistry) {
     let resolvedOptions = options;
+    const warnings = [];
     if (resolvedOptions.template !== undefined) {
         const templateName = resolvedOptions.template.trim();
         if (templateName.length === 0) {
@@ -1056,7 +1062,7 @@ async function resolveCreateTypeSelection(options, global, pmRoot, settings, typ
             ? resolveTypeName(synonymCanonical, typeRegistry)
             : undefined;
         if (synonymResolved) {
-            printError(`[pm] note: type '${resolvedOptions.type.trim()}' is not defined; using closest match '${synonymResolved}'. Run 'pm schema add-type "${resolvedOptions.type.trim()}"' to track it as a distinct type.`);
+            warnings.push(`type_coercion:${resolvedOptions.type.trim()}:${synonymResolved}`);
             resolvedOptions.type = synonymResolved;
             resolvedTypeName = synonymResolved;
         }
@@ -1089,7 +1095,14 @@ async function resolveCreateTypeSelection(options, global, pmRoot, settings, typ
         throw new PmCliError(`--schedule-preset ${schedulePreset} is only supported for Reminder, Meeting, or Event types`, EXIT_CODE.USAGE);
     }
     const createMode = resolveEffectiveCreateMode(resolvedOptions.createMode, schedulePreset, settings.governance.create_mode_default);
-    return { resolvedOptions, typeDefinition, type, schedulePreset, createMode };
+    return {
+        resolvedOptions,
+        typeDefinition,
+        type,
+        schedulePreset,
+        createMode,
+        warnings,
+    };
 }
 /** Seed the explicit-unset and clear-option key sets from the parsed `--unset` targets, then fold in each enabled `--clear-<collection>` flag: it marks the collection's item-metadata key as explicitly unset and its option key as cleared, and rejects combining a clear flag with its own value flag. Returns the augmented sets used downstream for required-flag relaxation and history messaging. */
 function collectCreateClearTargets(resolvedOptions, unsetTargets) {
@@ -1310,11 +1323,31 @@ function assertNoCreateFieldUnsetConflicts(registeredItemFieldValues, runtimeCre
 }
 /** Throw the aggregated `missing_required_option` error when a type's required create options and/or required type-option keys were not all supplied in one invocation. Builds a type-aware valid example and staged-onboarding next steps (a strict-mode invocation also carries a compact recovery envelope). A no-op when nothing is missing. */
 function assertNoMissingRequiredCreateOptions(params) {
-    const { combinedMissingFlags, typeDefinition, missingRequiredCreateFlags, missingRequiredTypeOptionKeys, openStatus, type, createMode, } = params;
+    const { combinedMissingFlags, typeDefinition, missingRequiredCreateFlags, missingRequiredTypeOptionKeys, openStatus, type, createMode, missingRequiredRuntimeFields, } = params;
     if (combinedMissingFlags.length === 0) {
         return;
     }
-    const nextValidExample = buildTypeSpecificCreateExample(typeDefinition, missingRequiredCreateFlags, missingRequiredTypeOptionKeys, openStatus);
+    const runtimeFieldSyntax = missingRequiredRuntimeFields.map((field) => {
+        const placeholder = field.type === "boolean"
+            ? "<true|false>"
+            : field.type === "array"
+                ? "<json-array>"
+                : field.type === "object"
+                    ? "<json-object>"
+                    : field.type === "number"
+                        ? "<number>"
+                        : field.type === "string_array" || field.repeatable
+                            ? "<value>"
+                            : "<string>";
+        return {
+            example: `--${field.cli_flag} ${placeholder}`,
+            description: `--${field.cli_flag} maps to ${field.metadata_key} (${field.type}${field.repeatable ? ", repeatable" : ""})`,
+        };
+    });
+    const nextValidExample = [
+        buildTypeSpecificCreateExample(typeDefinition, missingRequiredCreateFlags, missingRequiredTypeOptionKeys, openStatus),
+        ...runtimeFieldSyntax.map((field) => field.example),
+    ].join(" ");
     const nextSteps = [
         `Run "pm create --help --type ${type}" for type-aware required option guidance.`,
     ];
@@ -1329,6 +1362,9 @@ function assertNoMissingRequiredCreateOptions(params) {
             nextSteps.push('For minimal scheduling inputs, try "--schedule-preset lightweight".');
         }
     }
+    if (runtimeFieldSyntax.length > 0) {
+        nextSteps.push(`Required custom field formats: ${runtimeFieldSyntax.map((field) => field.description).join("; ")}.`);
+    }
     const errorMessage = combinedMissingFlags.length === 1
         ? `Missing required option ${combinedMissingFlags[0]} for type "${type}"`
         : `Missing required options ${combinedMissingFlags.join(", ")} for type "${type}"`;
@@ -1553,6 +1589,8 @@ export async function runCreate(options, global) {
     const extensionFieldNames = collectRegisteredItemFieldNames(extensionRegistrations);
     const registeredItemFieldValues = parseRegisteredItemFieldAssignments(resolvedOptions.field, extensionRegistrations);
     const runtimeCreateFieldValues = collectRuntimeCreateFieldValues(resolvedOptions, runtimeFieldRegistry, type);
+    const missingRequiredRuntimeFlagSet = new Set(runtimeCreateFieldValues.missing_required_flags);
+    const missingRequiredRuntimeFields = runtimeFieldRegistry.definitions.filter((field) => missingRequiredRuntimeFlagSet.has(`--${field.cli_flag}`));
     assertNoCreateFieldUnsetConflicts(registeredItemFieldValues, runtimeCreateFieldValues, unsetTargets);
     const missingRequiredTypeOptionKeys = collectMissingRequiredTypeOptionKeys(validatedTypeOptions.errors, type);
     const missingRequiredTypeOptionFlags = missingRequiredTypeOptionKeys.map((key) => `--type-option ${key}=<value>`);
@@ -1572,6 +1610,7 @@ export async function runCreate(options, global) {
         openStatus: statusRegistry.open_status,
         type,
         createMode,
+        missingRequiredRuntimeFields,
     });
     assertNoInvalidTypeOptions(validatedTypeOptions.errors, type, typeDefinition, statusRegistry);
     const id = await resolveCreateItemId({
@@ -1619,7 +1658,10 @@ export async function runCreate(options, global) {
         ? "warn"
         : settings.validation.parent_reference;
     const sprintReleasePolicy = settings.validation.sprint_release_format;
-    const validationWarnings = collectCreateScheduleWarnings(type, id, deadline, reminders.values, events.values);
+    const validationWarnings = [
+        ...typeSelection.warnings,
+        ...collectCreateScheduleWarnings(type, id, deadline, reminders.values, events.values),
+    ];
     const parentValidation = await resolveCreateParentWithWarnings({
         itemId: id,
         parent,
@@ -1651,6 +1693,14 @@ export async function runCreate(options, global) {
     });
     const dependencyValues = blockedByResolution.dependencyValues;
     assertDependencyEdgesAllowed(id, dependencyValues);
+    validationWarnings.push(...(await assertDependencyTargetsResolvable({
+        pmRoot,
+        dependencies: dependencyValues,
+        idPrefix: settings.id_prefix,
+        itemFormat: settings.item_format,
+        typeToFolder: typeRegistry.type_to_folder,
+        allowUnresolved: resolvedOptions.allowUnresolvedDeps,
+    })));
     status = blockedByResolution.status;
     const blockedReason = resolveUnsettableOptionalString(unsetKeys, "blocked_reason", resolvedOptions.blockedReason);
     const unblockNote = resolveUnsettableOptionalString(unsetKeys, "unblock_note", resolvedOptions.unblockNote);
@@ -1788,6 +1838,9 @@ export async function runCreate(options, global) {
         allowDuplicate: resolvedOptions.allowDuplicate,
     });
     const outputItem = structuredClone(itemMetadata);
+    if (createMode === "strict" && explicitUnsets.has("dependencies")) {
+        outputItem.dependencies = [];
+    }
     // GH-216: nudge agents toward the underutilized in_progress state instead of
     // jumping open -> closed. Only surfaces for workable types created in the open
     // status when the workflow defines a distinct in_progress status to move to.
@@ -1835,4 +1888,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=af455a7c-354f-54be-99e0-833c9f2710c5
+//# debugId=ffa56c1a-d98c-566a-81c5-4ad5608aa26c

package/dist/sdk/lifecycle/focus.js

@@ -4,8 +4,9 @@
  * Implements the SDK-owned focus lifecycle operation shared by every surface.
  */
 
-!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]="d51ebf7a-d759-5a6b-9a4f-810139a1688c")}catch(e){}}();
-import { pathExists, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, EXIT_CODE, PmCliError, clearFocusedItem, getFocusedItem, setFocusedItem, buildItemNotFoundError, locateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
+!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]="0f43df79-0b27-53b3-b8bd-9f2a35561733")}catch(e){}}();
+import { pathExists, getActiveExtensionRegistrations, normalizeItemId, resolveItemTypeRegistry, EXIT_CODE, PmCliError, clearFocusedItem, getFocusedItem, setFocusedItem, buildItemNotFoundError, locateItem, readLocatedItem, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, resolveClaimPrincipal, } from "../runtime-primitives.js";
+import { recordFocusSemanticAttribution } from "../context/semantic-session-attribution.js";
 async function ensureInitialized(pmRoot) {
     if (!(await pathExists(getSettingsPath(pmRoot)))) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
@@ -20,7 +21,10 @@ export async function runFocus(id, options, global) {
         if (id !== undefined) {
             throw new PmCliError("pm focus --clear does not take an item id. Use 'pm focus --clear' to clear focus or 'pm focus <id>' to set it.", EXIT_CODE.USAGE);
         }
+        const settings = await readSettings(pmRoot);
+        const principal = resolveClaimPrincipal(resolveAuthor(undefined, settings.author_default));
         await clearFocusedItem(pmRoot);
+        await recordFocusSemanticAttribution({ pmRoot, settings, principal });
         return {
             action: "clear",
             focused_item: null,
@@ -56,6 +60,12 @@ export async function runFocus(id, options, global) {
     const loaded = await readLocatedItem(located, { schema: settings.schema });
     const title = nonEmptyTitleOrNull(loaded.document.metadata.title);
     await setFocusedItem(pmRoot, normalizedId);
+    await recordFocusSemanticAttribution({
+        pmRoot,
+        settings,
+        principal: resolveClaimPrincipal(resolveAuthor(undefined, settings.author_default)),
+        itemId: normalizedId,
+    });
     return {
         action: "set",
         focused_item: normalizedId,
@@ -80,4 +90,4 @@ function nonEmptyTitleOrNull(title) {
     return title.trim().length > 0 ? title : null;
 }
 //# sourceMappingURL=focus.js.map
-//# debugId=d51ebf7a-d759-5a6b-9a4f-810139a1688c
+//# debugId=0f43df79-0b27-53b3-b8bd-9f2a35561733

package/dist/sdk/lifecycle/plan.js

@@ -4,10 +4,11 @@
  * 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]="dc87393e-61e3-5d43-a756-d5f156faf29e")}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]="3d5ea029-26ef-51bc-bacc-b1d4d807a024")}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";
+import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 /** Public contract for plan subcommands, shared by SDK and presentation-layer consumers. */
 export const PLAN_SUBCOMMANDS = [
     "create",
@@ -1567,7 +1568,11 @@ const PLAN_DISPATCHERS = {
 function resolvePlanDispatcher(subcommand) {
     const dispatcher = PLAN_DISPATCHERS[subcommand];
     if (!dispatcher) {
-        throw new PmCliError(`Unknown pm plan subcommand "${subcommand}"`, EXIT_CODE.USAGE);
+        throw createUnknownSubcommandError({
+            command_path: "plan",
+            token: subcommand,
+            allowed: PLAN_SUBCOMMANDS,
+        });
     }
     return dispatcher;
 }
@@ -1582,4 +1587,4 @@ export const _testOnlyPlanCommand = {
     changedPlanMetadataFields,
 };
 //# sourceMappingURL=plan.js.map
-//# debugId=dc87393e-61e3-5d43-a756-d5f156faf29e
+//# debugId=3d5ea029-26ef-51bc-bacc-b1d4d807a024

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. */