@unbrained/pm-cli 2026.5.18 → 2026.5.27

package/dist/cli/commands/update.js

@@ -1,11 +1,14 @@
 
-!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]="98e2bc37-91cc-5340-b212-da1076fc5857")}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]="94e19c77-3288-5a43-a8b2-6b9f15d4f234")}catch(e){}}();
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, } from "../../core/item/type-registry.js";
 import { normalizeItemId } from "../../core/item/id.js";
+import { toItemRecord } from "../../core/item/item-record.js";
+import { buildInvalidTypeError } from "../../core/schema/item-types-file.js";
 import { normalizeParentReferenceValue, validateMissingParentReference, } from "../../core/item/parent-reference-policy.js";
 import { validateSprintOrReleaseValue } from "../../core/item/sprint-release-format.js";
 import { createStdinTokenResolver, parseCsvKv, parseOptionalNumber, parseTags } from "../../core/item/parse.js";
+import { resolvePriority } from "../../core/item/priority.js";
 import { normalizeStatusInput } from "../../core/item/status.js";
 import { collectRuntimeUpdateFieldValues } from "../../core/schema/runtime-field-values.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
@@ -19,9 +22,11 @@ import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { runClose } from "./close.js";
 import { normalizeRiskInput, normalizeSeverityInput, parseConfidenceInput, parseRegressionInput, } from "./metadata-normalizers.js";
-import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, RISK_VALUES, } from "../../types/index.js";
+import { resolveEventEndAt } from "./event-validation-messages.js";
+import { assertNoLegacyNoneToken, assertNoLegacyNoneTokens, isLegacyNoneToken } from "./legacy-none-tokens.js";
+import { ensureEnumValue as ensureEnum, parseEventBoolean, parseRecurrenceRule } from "./recurrence-parsers.js";
+import { DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, RISK_VALUES, } from "../../types/index.js";
 import { parseDocs, parseFiles, parseLogSeed, parseTests } from "./create.js";
-const LEGACY_NONE_TOKENS = new Set(["none", "null"]);
 const UPDATE_UNSET_FIELD_DEFINITIONS = [
     { canonical: "tags", aliases: ["tags"], optionKey: "tags", frontMatterKey: "tags" },
     { canonical: "close-reason", aliases: ["close_reason", "close-reason"], optionKey: "closeReason", frontMatterKey: "close_reason" },
@@ -167,30 +172,6 @@ function toAuthor(candidate, defaultAuthor) {
     const trimmed = resolved.trim();
     return trimmed || "unknown";
 }
-function isLegacyNoneToken(value) {
-    if (value === undefined) {
-        return false;
-    }
-    return LEGACY_NONE_TOKENS.has(value.trim().toLowerCase());
-}
-function assertNoLegacyNoneToken(value, flag, replacementHint) {
-    if (!isLegacyNoneToken(value)) {
-        return;
-    }
-    const suffix = replacementHint ? ` ${replacementHint}` : "";
-    throw new PmCliError(`${flag} no longer accepts "none" or "null".${suffix}`.trim(), EXIT_CODE.USAGE);
-}
-function assertNoLegacyNoneTokens(values, flag, replacementHint) {
-    if (!values || values.length === 0) {
-        return;
-    }
-    const hasLegacyToken = values.some((value) => isLegacyNoneToken(value));
-    if (!hasLegacyToken) {
-        return;
-    }
-    const suffix = replacementHint ? ` ${replacementHint}` : "";
-    throw new PmCliError(`${flag} no longer accepts "none" or "null".${suffix}`.trim(), EXIT_CODE.USAGE);
-}
 const UPDATE_LEGACY_NONE_COLLECTION_NORMALIZERS = [
     { optionKey: "dep", clearFlagKey: "clearDeps", valueFlag: "--dep", clearFlag: "--clear-deps", disableReplaceFlagKey: "replaceDeps" },
     { optionKey: "comment", clearFlagKey: "clearComments", valueFlag: "--comment", clearFlag: "--clear-comments" },
@@ -478,12 +459,6 @@ function enforceAllowAuditUpdateScope(options, clearFrontMatterKeys) {
         throw new PmCliError(`--allow-audit-update only supports non-lifecycle metadata fields. Remove restricted options: ${disallowedFlags.join(", ")}`, EXIT_CODE.USAGE);
     }
 }
-function ensureEnum(value, allowed, label) {
-    if (!allowed.includes(value)) {
-        throw new PmCliError(`Invalid ${label} value "${value}"`, EXIT_CODE.USAGE);
-    }
-    return value;
-}
 function parseStatus(value, statusRegistry) {
     const normalized = normalizeStatusInput(value, statusRegistry);
     if (!normalized) {
@@ -492,16 +467,13 @@ function parseStatus(value, statusRegistry) {
     }
     return normalized;
 }
-function weekdayOrderIndex(value) {
-    return RECURRENCE_WEEKDAY_VALUES.indexOf(value);
-}
 function parseReminderEntries(raw, nowValue) {
     return raw.map((entry) => {
         const kv = parseCsvKv(entry, "--reminder");
-        const atRaw = kv.at?.trim();
-        const textRaw = kv.text?.trim();
+        const atRaw = (kv.at ?? kv.date)?.trim();
+        const textRaw = (kv.text ?? kv.title)?.trim();
         if (!atRaw || !textRaw) {
-            throw new PmCliError("--reminder requires at=<iso|relative> and text=<value>", EXIT_CODE.USAGE);
+            throw new PmCliError("--reminder requires at=<iso|relative> or date=<iso|relative>, plus text=<value> or title=<value>", EXIT_CODE.USAGE);
         }
         return {
             at: resolveIsoOrRelative(atRaw, nowValue, "reminder.at"),
@@ -509,75 +481,6 @@ function parseReminderEntries(raw, nowValue) {
         };
     });
 }
-function parseEventBoolean(value, flag) {
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "true" || normalized === "1" || normalized === "yes") {
-        return true;
-    }
-    if (normalized === "false" || normalized === "0" || normalized === "no") {
-        return false;
-    }
-    throw new PmCliError(`${flag} must be one of true|false|1|0|yes|no`, EXIT_CODE.USAGE);
-}
-function parseDelimitedList(raw) {
-    if (!raw) {
-        return [];
-    }
-    return raw
-        .split("|")
-        .map((value) => value.trim())
-        .filter((value) => value.length > 0);
-}
-function parseRecurrenceRule(kv, startAt, nowValue) {
-    const freqRaw = kv.recur_freq?.trim();
-    const intervalRaw = kv.recur_interval?.trim();
-    const countRaw = kv.recur_count?.trim();
-    const untilRaw = kv.recur_until?.trim();
-    const byWeekdayRaw = kv.recur_by_weekday?.trim();
-    const byMonthDayRaw = kv.recur_by_month_day?.trim();
-    const exdatesRaw = kv.recur_exdates?.trim();
-    const recurrenceInputsProvided = [freqRaw, intervalRaw, countRaw, untilRaw, byWeekdayRaw, byMonthDayRaw, exdatesRaw].some((value) => value !== undefined);
-    if (!recurrenceInputsProvided) {
-        return undefined;
-    }
-    if (!freqRaw) {
-        throw new PmCliError("--event recurrence fields require recur_freq=<daily|weekly|monthly|yearly>", EXIT_CODE.USAGE);
-    }
-    const freq = ensureEnum(freqRaw.toLowerCase(), RECURRENCE_FREQUENCY_VALUES, "event recurrence frequency");
-    const interval = intervalRaw ? parseOptionalNumber(intervalRaw, "event recur_interval") : undefined;
-    if (interval !== undefined && (!Number.isInteger(interval) || interval < 1)) {
-        throw new PmCliError("--event recur_interval must be an integer >= 1", EXIT_CODE.USAGE);
-    }
-    const count = countRaw ? parseOptionalNumber(countRaw, "event recur_count") : undefined;
-    if (count !== undefined && (!Number.isInteger(count) || count < 1)) {
-        throw new PmCliError("--event recur_count must be an integer >= 1", EXIT_CODE.USAGE);
-    }
-    const until = untilRaw ? resolveIsoOrRelative(untilRaw, nowValue, "event.recur_until") : undefined;
-    if (until && until < startAt) {
-        throw new PmCliError("--event recur_until must be at or after start", EXIT_CODE.USAGE);
-    }
-    const byWeekday = Array.from(new Set(parseDelimitedList(byWeekdayRaw)
-        .map((value) => ensureEnum(value.toLowerCase(), RECURRENCE_WEEKDAY_VALUES, "event weekday")))).sort((left, right) => weekdayOrderIndex(left) -
-        weekdayOrderIndex(right));
-    const byMonthDay = Array.from(new Set(parseDelimitedList(byMonthDayRaw)
-        .map((value) => {
-        const day = parseOptionalNumber(value, "event recur_by_month_day");
-        if (!Number.isInteger(day) || day < 1 || day > 31) {
-            throw new PmCliError("--event recur_by_month_day values must be integers 1..31", EXIT_CODE.USAGE);
-        }
-        return day;
-    }))).sort((left, right) => left - right);
-    const exdates = Array.from(new Set(parseDelimitedList(exdatesRaw).map((value) => resolveIsoOrRelative(value, nowValue, "event.recur_exdates")))).sort((left, right) => left.localeCompare(right));
-    return {
-        freq,
-        interval,
-        count,
-        until,
-        by_weekday: byWeekday.length > 0 ? byWeekday : undefined,
-        by_month_day: byMonthDay.length > 0 ? byMonthDay : undefined,
-        exdates: exdates.length > 0 ? exdates : undefined,
-    };
-}
 function parseEventEntries(raw, nowValue) {
     return raw.map((entry) => {
         const kv = parseCsvKv(entry, "--event");
@@ -587,10 +490,8 @@ function parseEventEntries(raw, nowValue) {
         }
         const startAt = resolveIsoOrRelative(startRaw, nowValue, "event.start");
         const endRaw = kv.end?.trim();
-        const endAt = endRaw ? resolveIsoOrRelative(endRaw, nowValue, "event.end") : undefined;
-        if (endAt && endAt <= startAt) {
-            throw new PmCliError("--event end must be after start", EXIT_CODE.USAGE);
-        }
+        const durationRaw = kv.duration?.trim();
+        const endAt = resolveEventEndAt(startAt, endRaw, durationRaw, nowValue);
         const titleRaw = kv.title;
         const descriptionRaw = kv.description;
         const locationRaw = kv.location;
@@ -612,7 +513,7 @@ function parseEventEntries(raw, nowValue) {
             throw new PmCliError("--event timezone must not be empty", EXIT_CODE.USAGE);
         }
         const allDayRaw = kv.all_day?.trim();
-        const recurrence = parseRecurrenceRule(kv, startAt, nowValue);
+        const recurrence = parseRecurrenceRule(kv, startAt, nowValue, "truthy");
         return {
             start_at: startAt,
             end_at: endAt,
@@ -750,6 +651,63 @@ function parseDependencyRemovals(raw, prefix) {
 function dependencyKey(value) {
     return `${value.id}::${value.kind}::${value.source_kind ?? ""}`;
 }
+// pm-kyd6: `--blocked-by` writes the `blocked_by` scalar, but the dependency
+// graph (`pm deps`) is built only from the `dependencies` array. Mirror the
+// behaviour create.ts already has so the metadata and the graph agree: a
+// resolvable blocker also gets a `blocked_by` dependency edge, clearing the
+// scalar removes that edge, and re-pointing it replaces the prior edge.
+function reconcileBlockedByDependency(current, nextBlockedById, nowIsoValue, author) {
+    let next = [...(current ?? [])];
+    let changed = false;
+    const filtered = next.filter((dep) => dep.kind !== "blocked_by" || dep.id === nextBlockedById);
+    if (filtered.length !== next.length) {
+        next = filtered;
+        changed = true;
+    }
+    if (nextBlockedById && !next.some((dep) => dep.kind === "blocked_by" && dep.id === nextBlockedById)) {
+        next.push({ id: nextBlockedById, kind: "blocked_by", created_at: nowIsoValue, author });
+        changed = true;
+    }
+    if (!changed) {
+        return { dependencies: current, changed: false };
+    }
+    return { dependencies: next.length > 0 ? next : undefined, changed: true };
+}
+// pm-kyd6: resolve the --blocked-by target before the synchronous mutate
+// callback so a real blocker can also become a `blocked_by` dependency edge.
+// `id` is set when the target resolves; `unresolved` carries the raw value when
+// --blocked-by points at an item that does not exist (the scalar is still set,
+// mirroring create.ts and the never-block missing-parent behaviour, but the
+// caller surfaces a warning so the metadata/graph mismatch is visible).
+async function resolveBlockedByDependencyTarget(blockedByOption, blockedByCleared, pmRoot, idPrefix, itemFormat, typeToFolder) {
+    if (blockedByOption === undefined || blockedByCleared) {
+        return {};
+    }
+    const blockedByValue = blockedByOption.trim();
+    if (blockedByValue.length === 0) {
+        return {};
+    }
+    const located = await locateItem(pmRoot, normalizeItemId(blockedByValue, idPrefix), idPrefix, itemFormat, typeToFolder);
+    return located ? { id: located.id } : { unresolved: blockedByValue };
+}
+// pm-kyd6: apply the reconciled blocked_by dependency edge to the item metadata
+// and record the `dependencies` change. Kept out of the mutate callback so the
+// large runUpdate function stays under the static-quality complexity budget.
+function applyBlockedByDependencyEdge(metadata, resolvedBlockedById, nowIsoValue, author, changedFields) {
+    const reconciled = reconcileBlockedByDependency(metadata.dependencies, resolvedBlockedById, nowIsoValue, author);
+    if (!reconciled.changed) {
+        return;
+    }
+    if (reconciled.dependencies === undefined) {
+        delete metadata.dependencies;
+    }
+    else {
+        metadata.dependencies = reconciled.dependencies;
+    }
+    if (!changedFields.includes("dependencies")) {
+        changedFields.push("dependencies");
+    }
+}
 function fileKey(value) {
     return `${value.path}::${value.scope}`;
 }
@@ -772,11 +730,7 @@ function matchesDependencySelector(value, selector) {
     return true;
 }
 function ensurePriority(raw) {
-    const parsed = parseOptionalNumber(raw, "priority (expected 0..4: 0=critical, 1=high, 2=medium, 3=low, 4=minimal)");
-    if (![0, 1, 2, 3, 4].includes(parsed)) {
-        throw new PmCliError("Priority must be 0..4 (0=critical, 1=high, 2=medium, 3=low, 4=minimal)", EXIT_CODE.USAGE);
-    }
-    return parsed;
+    return resolvePriority(raw);
 }
 function normalizeUpdatePolicyOptionKey(raw, typeName) {
     const canonical = canonicalizeCommandOptionKey("update", raw);
@@ -1134,6 +1088,13 @@ export async function runUpdate(id, options, global) {
             parentReferenceWarnings.push(...validateMissingParentReference(normalizedParentId, parentReferencePolicy).warnings);
         }
     }
+    // pm-kyd6: resolve the --blocked-by target up front (async) so the sync
+    // mutate callback can mirror create.ts and add a `blocked_by` dependency edge.
+    const blockedByResolution = await resolveBlockedByDependencyTarget(options.blockedBy, clearFrontMatterKeys.has("blocked_by"), pmRoot, settings.id_prefix, settings.item_format, typeRegistry.type_to_folder);
+    const resolvedBlockedByDependencyId = blockedByResolution.id;
+    if (blockedByResolution.unresolved !== undefined) {
+        parentReferenceWarnings.push(`blocked_by_unresolved:${blockedByResolution.unresolved}`);
+    }
     const fieldFlags = {
         title: options.title !== undefined,
         description: options.description !== undefined,
@@ -1210,37 +1171,47 @@ export async function runUpdate(id, options, global) {
         }
         const { document } = await readLocatedItem(located, { schema: settings.schema });
         return {
-            item: document.metadata,
+            item: toItemRecord(document.metadata),
             changed_fields: [],
             warnings: ["noop_no_update_fields"],
         };
     }
-    if (fieldFlags.status && fieldFlags.closeReason) {
+    // `pm update --status <close_status>` always routes to the auditable close
+    // workflow so agents are never blocked by close-through-update errors. Any
+    // other field updates in the same call are applied first, then the item is
+    // closed with the supplied --close-reason (or a derived default when omitted).
+    if (fieldFlags.status) {
         const targetStatus = normalizeStatusInput(options.status, statusRegistry);
         if (targetStatus === statusRegistry.close_status) {
-            const otherFieldsChanged = Object.entries(fieldFlags).some(([key, value]) => value && key !== "status" && key !== "closeReason");
-            if (otherFieldsChanged) {
-                throw new PmCliError(`Cannot combine other field updates with --status ${statusRegistry.close_status} --close-reason. Run pm update for non-close fields, then pm close <id> "<reason>" separately.`, EXIT_CODE.USAGE, {
-                    code: "close_through_update",
-                    why: "Closing requires explicit pm close to capture validation; combining other field updates in the same call would mask the close audit trail.",
-                    examples: [
-                        `pm update ${id} --title "<title>"`,
-                        `pm close ${id} "${options.closeReason}" --author "${author}"`,
-                    ],
-                    nextSteps: [
-                        "Split into two commands: pm update <id> --<field> <value>; pm close <id> \"<reason>\".",
-                    ],
-                });
+            const otherFieldKeys = Object.entries(fieldFlags)
+                .filter(([key, value]) => value && key !== "status" && key !== "closeReason")
+                .map(([key]) => key);
+            const routeWarnings = [];
+            let preChangedFields = [];
+            if (otherFieldKeys.length > 0) {
+                const preUpdate = await runUpdate(id, { ...options, status: undefined, closeReason: undefined, message: undefined }, global);
+                preChangedFields = preUpdate.changed_fields;
+                routeWarnings.push(...preUpdate.warnings);
             }
-            const closeResult = await runClose(id, options.closeReason, {
+            const explicitReason = typeof options.closeReason === "string" ? options.closeReason.trim() : "";
+            const fallbackMessage = typeof options.message === "string" ? options.message.trim() : "";
+            const closeReason = explicitReason || fallbackMessage || "Closed via pm update";
+            // Only flag a defaulted reason when neither --close-reason nor --message
+            // supplied any text and we had to invent the generic placeholder.
+            const reasonDefaulted = explicitReason.length === 0 && fallbackMessage.length === 0;
+            const closeResult = await runClose(id, closeReason, {
                 author: options.author,
                 message: options.message,
                 force: options.force,
             }, global);
+            const warnings = [...routeWarnings, ...closeResult.warnings, "auto_routed_from_update_to_close"];
+            if (reasonDefaulted) {
+                warnings.push("close_reason_defaulted");
+            }
             return {
                 item: closeResult.item,
-                changed_fields: closeResult.changed_fields,
-                warnings: [...closeResult.warnings, "auto_routed_from_update_to_close"],
+                changed_fields: [...preChangedFields, ...closeResult.changed_fields],
+                warnings,
             };
         }
     }
@@ -1261,6 +1232,27 @@ export async function runUpdate(id, options, global) {
             const changedFields = [];
             const warnings = [];
             let activeTypeName = resolveTypeName(document.metadata.type, typeRegistry) ?? document.metadata.type;
+            // Declarative set-or-clear helpers for the many string scalar fields that
+            // share an identical shape: set from `--flag` (optionally transformed) or
+            // delete when `--unset <field>` was requested, then record the change.
+            // Each call is placed in the same position the inline block occupied so
+            // the order of `changedFields` is preserved exactly (pm-why9).
+            const metadataRecord = toItemRecord(document.metadata);
+            const setOrClearScalar = (optionValue, metadataKey, transform) => {
+                if (optionValue === undefined && !clearFrontMatterKeys.has(metadataKey)) {
+                    return;
+                }
+                if (clearFrontMatterKeys.has(metadataKey)) {
+                    delete metadataRecord[metadataKey];
+                }
+                else {
+                    metadataRecord[metadataKey] = transform(optionValue);
+                }
+                changedFields.push(metadataKey);
+            };
+            const setOrClearTrimScalar = (optionValue, metadataKey) => {
+                setOrClearScalar(optionValue, metadataKey, (value) => value.trim());
+            };
             if (options.title !== undefined) {
                 document.metadata.title = options.title;
                 changedFields.push("title");
@@ -1276,21 +1268,9 @@ export async function runUpdate(id, options, global) {
             const previousStatus = document.metadata.status;
             const previousStatusNormalized = normalizeStatusInput(previousStatus, statusRegistry) ?? previousStatus;
             if (options.status !== undefined) {
+                // Close-status routing (with reason + audit) is handled before mutateItem
+                // by the close gate above, so only non-close transitions reach this path.
                 const status = parseStatus(options.status, statusRegistry);
-                if (status === statusRegistry.close_status) {
-                    throw new PmCliError(`Invalid --status value "${statusRegistry.close_status}". Use "pm close <ID> <TEXT>" to close an item.`, EXIT_CODE.USAGE, {
-                        code: "close_through_update",
-                        why: "Closing requires a close reason and optional validation checks that pm update cannot enforce. Use pm close for auditable close workflows.",
-                        examples: [
-                            `pm close ${id} "All acceptance criteria met" --author "${author}" --message "Close: verified"`,
-                            `pm close ${id} "Resolved" --validate-close warn --author "${author}"`,
-                        ],
-                        nextSteps: [
-                            'Use "pm close <ID> <reason>" to close with required close reason and optional --validate-close.',
-                            'To cancel instead, use "pm update <ID> --status canceled".',
-                        ],
-                    });
-                }
                 document.metadata.status = status;
                 if (status === statusRegistry.canceled_status) {
                     delete document.metadata.assignee;
@@ -1324,7 +1304,7 @@ export async function runUpdate(id, options, global) {
             if (options.type !== undefined) {
                 const resolvedTypeName = resolveTypeName(options.type, typeRegistry);
                 if (!resolvedTypeName) {
-                    throw new PmCliError(`Invalid type value "${options.type}". Allowed: ${typeRegistry.types.join(", ")}`, EXIT_CODE.USAGE);
+                    throw new PmCliError(buildInvalidTypeError(options.type, typeRegistry.types), EXIT_CODE.USAGE);
                 }
                 document.metadata.type = resolvedTypeName;
                 activeTypeName = resolvedTypeName;
@@ -1482,42 +1462,10 @@ export async function runUpdate(id, options, global) {
                 document.metadata.tags = clearFrontMatterKeys.has("tags") ? [] : parseTags(options.tags);
                 changedFields.push("tags");
             }
-            if (options.deadline !== undefined || clearFrontMatterKeys.has("deadline")) {
-                if (clearFrontMatterKeys.has("deadline")) {
-                    delete document.metadata.deadline;
-                }
-                else {
-                    document.metadata.deadline = resolveIsoOrRelative(options.deadline, new Date(), "deadline");
-                }
-                changedFields.push("deadline");
-            }
-            if (options.estimatedMinutes !== undefined || clearFrontMatterKeys.has("estimated_minutes")) {
-                if (clearFrontMatterKeys.has("estimated_minutes")) {
-                    delete document.metadata.estimated_minutes;
-                }
-                else {
-                    document.metadata.estimated_minutes = parseOptionalNumber(options.estimatedMinutes, "estimated-minutes");
-                }
-                changedFields.push("estimated_minutes");
-            }
-            if (options.acceptanceCriteria !== undefined || clearFrontMatterKeys.has("acceptance_criteria")) {
-                if (clearFrontMatterKeys.has("acceptance_criteria")) {
-                    delete document.metadata.acceptance_criteria;
-                }
-                else {
-                    document.metadata.acceptance_criteria = options.acceptanceCriteria;
-                }
-                changedFields.push("acceptance_criteria");
-            }
-            if (options.definitionOfReady !== undefined || clearFrontMatterKeys.has("definition_of_ready")) {
-                if (clearFrontMatterKeys.has("definition_of_ready")) {
-                    delete document.metadata.definition_of_ready;
-                }
-                else {
-                    document.metadata.definition_of_ready = options.definitionOfReady.trim();
-                }
-                changedFields.push("definition_of_ready");
-            }
+            setOrClearScalar(options.deadline, "deadline", (value) => resolveIsoOrRelative(value, nowValue, "deadline"));
+            setOrClearScalar(options.estimatedMinutes, "estimated_minutes", (value) => parseOptionalNumber(value, "estimated-minutes"));
+            setOrClearScalar(options.acceptanceCriteria, "acceptance_criteria", (value) => value);
+            setOrClearTrimScalar(options.definitionOfReady, "definition_of_ready");
             const orderRaw = options.order ?? options.rank;
             if (orderRaw !== undefined || clearFrontMatterKeys.has("order")) {
                 if (clearFrontMatterKeys.has("order")) {
@@ -1532,60 +1480,12 @@ export async function runUpdate(id, options, global) {
                 }
                 changedFields.push("order");
             }
-            if (options.goal !== undefined || clearFrontMatterKeys.has("goal")) {
-                if (clearFrontMatterKeys.has("goal")) {
-                    delete document.metadata.goal;
-                }
-                else {
-                    document.metadata.goal = options.goal.trim();
-                }
-                changedFields.push("goal");
-            }
-            if (options.objective !== undefined || clearFrontMatterKeys.has("objective")) {
-                if (clearFrontMatterKeys.has("objective")) {
-                    delete document.metadata.objective;
-                }
-                else {
-                    document.metadata.objective = options.objective.trim();
-                }
-                changedFields.push("objective");
-            }
-            if (options.value !== undefined || clearFrontMatterKeys.has("value")) {
-                if (clearFrontMatterKeys.has("value")) {
-                    delete document.metadata.value;
-                }
-                else {
-                    document.metadata.value = options.value.trim();
-                }
-                changedFields.push("value");
-            }
-            if (options.impact !== undefined || clearFrontMatterKeys.has("impact")) {
-                if (clearFrontMatterKeys.has("impact")) {
-                    delete document.metadata.impact;
-                }
-                else {
-                    document.metadata.impact = options.impact.trim();
-                }
-                changedFields.push("impact");
-            }
-            if (options.outcome !== undefined || clearFrontMatterKeys.has("outcome")) {
-                if (clearFrontMatterKeys.has("outcome")) {
-                    delete document.metadata.outcome;
-                }
-                else {
-                    document.metadata.outcome = options.outcome.trim();
-                }
-                changedFields.push("outcome");
-            }
-            if (options.whyNow !== undefined || clearFrontMatterKeys.has("why_now")) {
-                if (clearFrontMatterKeys.has("why_now")) {
-                    delete document.metadata.why_now;
-                }
-                else {
-                    document.metadata.why_now = options.whyNow.trim();
-                }
-                changedFields.push("why_now");
-            }
+            setOrClearTrimScalar(options.goal, "goal");
+            setOrClearTrimScalar(options.objective, "objective");
+            setOrClearTrimScalar(options.value, "value");
+            setOrClearTrimScalar(options.impact, "impact");
+            setOrClearTrimScalar(options.outcome, "outcome");
+            setOrClearTrimScalar(options.whyNow, "why_now");
             if (options.assignee !== undefined || clearFrontMatterKeys.has("assignee")) {
                 if (clearFrontMatterKeys.has("assignee")) {
                     delete document.metadata.assignee;
@@ -1607,33 +1507,9 @@ export async function runUpdate(id, options, global) {
                 }
                 changedFields.push("parent");
             }
-            if (options.reviewer !== undefined || clearFrontMatterKeys.has("reviewer")) {
-                if (clearFrontMatterKeys.has("reviewer")) {
-                    delete document.metadata.reviewer;
-                }
-                else {
-                    document.metadata.reviewer = options.reviewer.trim();
-                }
-                changedFields.push("reviewer");
-            }
-            if (options.risk !== undefined || clearFrontMatterKeys.has("risk")) {
-                if (clearFrontMatterKeys.has("risk")) {
-                    delete document.metadata.risk;
-                }
-                else {
-                    document.metadata.risk = ensureEnum(normalizeRiskInput(options.risk), RISK_VALUES, "risk");
-                }
-                changedFields.push("risk");
-            }
-            if (options.confidence !== undefined || clearFrontMatterKeys.has("confidence")) {
-                if (clearFrontMatterKeys.has("confidence")) {
-                    delete document.metadata.confidence;
-                }
-                else {
-                    document.metadata.confidence = parseConfidenceInput(options.confidence);
-                }
-                changedFields.push("confidence");
-            }
+            setOrClearTrimScalar(options.reviewer, "reviewer");
+            setOrClearScalar(options.risk, "risk", (value) => ensureEnum(normalizeRiskInput(value), RISK_VALUES, "risk"));
+            setOrClearScalar(options.confidence, "confidence", (value) => parseConfidenceInput(value));
             if (options.sprint !== undefined || clearFrontMatterKeys.has("sprint")) {
                 if (clearFrontMatterKeys.has("sprint")) {
                     delete document.metadata.sprint;
@@ -1664,133 +1540,23 @@ export async function runUpdate(id, options, global) {
                     document.metadata.blocked_by = options.blockedBy.trim();
                 }
                 changedFields.push("blocked_by");
+                // pm-kyd6: keep the dependency graph in sync with the blocked_by scalar.
+                applyBlockedByDependencyEdge(document.metadata, resolvedBlockedByDependencyId, nowIso, author, changedFields);
             }
-            if (options.blockedReason !== undefined || clearFrontMatterKeys.has("blocked_reason")) {
-                if (clearFrontMatterKeys.has("blocked_reason")) {
-                    delete document.metadata.blocked_reason;
-                }
-                else {
-                    document.metadata.blocked_reason = options.blockedReason.trim();
-                }
-                changedFields.push("blocked_reason");
-            }
-            if (options.unblockNote !== undefined || clearFrontMatterKeys.has("unblock_note")) {
-                if (clearFrontMatterKeys.has("unblock_note")) {
-                    delete document.metadata.unblock_note;
-                }
-                else {
-                    document.metadata.unblock_note = options.unblockNote.trim();
-                }
-                changedFields.push("unblock_note");
-            }
-            if (options.reporter !== undefined || clearFrontMatterKeys.has("reporter")) {
-                if (clearFrontMatterKeys.has("reporter")) {
-                    delete document.metadata.reporter;
-                }
-                else {
-                    document.metadata.reporter = options.reporter.trim();
-                }
-                changedFields.push("reporter");
-            }
-            if (options.severity !== undefined || clearFrontMatterKeys.has("severity")) {
-                if (clearFrontMatterKeys.has("severity")) {
-                    delete document.metadata.severity;
-                }
-                else {
-                    document.metadata.severity = ensureEnum(normalizeSeverityInput(options.severity), ISSUE_SEVERITY_VALUES, "severity");
-                }
-                changedFields.push("severity");
-            }
-            if (options.environment !== undefined || clearFrontMatterKeys.has("environment")) {
-                if (clearFrontMatterKeys.has("environment")) {
-                    delete document.metadata.environment;
-                }
-                else {
-                    document.metadata.environment = options.environment.trim();
-                }
-                changedFields.push("environment");
-            }
-            if (options.reproSteps !== undefined || clearFrontMatterKeys.has("repro_steps")) {
-                if (clearFrontMatterKeys.has("repro_steps")) {
-                    delete document.metadata.repro_steps;
-                }
-                else {
-                    document.metadata.repro_steps = options.reproSteps.trim();
-                }
-                changedFields.push("repro_steps");
-            }
-            if (options.resolution !== undefined || clearFrontMatterKeys.has("resolution")) {
-                if (clearFrontMatterKeys.has("resolution")) {
-                    delete document.metadata.resolution;
-                }
-                else {
-                    document.metadata.resolution = options.resolution.trim();
-                }
-                changedFields.push("resolution");
-            }
-            if (options.expectedResult !== undefined || clearFrontMatterKeys.has("expected_result")) {
-                if (clearFrontMatterKeys.has("expected_result")) {
-                    delete document.metadata.expected_result;
-                }
-                else {
-                    document.metadata.expected_result = options.expectedResult.trim();
-                }
-                changedFields.push("expected_result");
-            }
-            if (options.actualResult !== undefined || clearFrontMatterKeys.has("actual_result")) {
-                if (clearFrontMatterKeys.has("actual_result")) {
-                    delete document.metadata.actual_result;
-                }
-                else {
-                    document.metadata.actual_result = options.actualResult.trim();
-                }
-                changedFields.push("actual_result");
-            }
-            if (options.affectedVersion !== undefined || clearFrontMatterKeys.has("affected_version")) {
-                if (clearFrontMatterKeys.has("affected_version")) {
-                    delete document.metadata.affected_version;
-                }
-                else {
-                    document.metadata.affected_version = options.affectedVersion.trim();
-                }
-                changedFields.push("affected_version");
-            }
-            if (options.fixedVersion !== undefined || clearFrontMatterKeys.has("fixed_version")) {
-                if (clearFrontMatterKeys.has("fixed_version")) {
-                    delete document.metadata.fixed_version;
-                }
-                else {
-                    document.metadata.fixed_version = options.fixedVersion.trim();
-                }
-                changedFields.push("fixed_version");
-            }
-            if (options.component !== undefined || clearFrontMatterKeys.has("component")) {
-                if (clearFrontMatterKeys.has("component")) {
-                    delete document.metadata.component;
-                }
-                else {
-                    document.metadata.component = options.component.trim();
-                }
-                changedFields.push("component");
-            }
-            if (options.regression !== undefined || clearFrontMatterKeys.has("regression")) {
-                if (clearFrontMatterKeys.has("regression")) {
-                    delete document.metadata.regression;
-                }
-                else {
-                    document.metadata.regression = parseRegressionInput(options.regression);
-                }
-                changedFields.push("regression");
-            }
-            if (options.customerImpact !== undefined || clearFrontMatterKeys.has("customer_impact")) {
-                if (clearFrontMatterKeys.has("customer_impact")) {
-                    delete document.metadata.customer_impact;
-                }
-                else {
-                    document.metadata.customer_impact = options.customerImpact.trim();
-                }
-                changedFields.push("customer_impact");
-            }
+            setOrClearTrimScalar(options.blockedReason, "blocked_reason");
+            setOrClearTrimScalar(options.unblockNote, "unblock_note");
+            setOrClearTrimScalar(options.reporter, "reporter");
+            setOrClearScalar(options.severity, "severity", (value) => ensureEnum(normalizeSeverityInput(value), ISSUE_SEVERITY_VALUES, "severity"));
+            setOrClearTrimScalar(options.environment, "environment");
+            setOrClearTrimScalar(options.reproSteps, "repro_steps");
+            setOrClearTrimScalar(options.resolution, "resolution");
+            setOrClearTrimScalar(options.expectedResult, "expected_result");
+            setOrClearTrimScalar(options.actualResult, "actual_result");
+            setOrClearTrimScalar(options.affectedVersion, "affected_version");
+            setOrClearTrimScalar(options.fixedVersion, "fixed_version");
+            setOrClearTrimScalar(options.component, "component");
+            setOrClearScalar(options.regression, "regression", (value) => parseRegressionInput(value));
+            setOrClearTrimScalar(options.customerImpact, "customer_impact");
             if (options.reminder !== undefined || clearFrontMatterKeys.has("reminders")) {
                 if (clearFrontMatterKeys.has("reminders")) {
                     delete document.metadata.reminders;
@@ -1813,10 +1579,10 @@ export async function runUpdate(id, options, global) {
                 if (!clearFrontMatterKeys.has(definition.metadata_key)) {
                     continue;
                 }
-                if (document.metadata[definition.metadata_key] === undefined) {
+                if (metadataRecord[definition.metadata_key] === undefined) {
                     continue;
                 }
-                delete document.metadata[definition.metadata_key];
+                delete metadataRecord[definition.metadata_key];
                 changedFields.push(definition.metadata_key);
             }
             const runtimeFieldUpdates = collectRuntimeUpdateFieldValues(options, runtimeFieldRegistry);
@@ -1824,14 +1590,14 @@ export async function runUpdate(id, options, global) {
                 if (clearFrontMatterKeys.has(fieldKey)) {
                     continue;
                 }
-                if (JSON.stringify(document.metadata[fieldKey]) === JSON.stringify(fieldValue)) {
+                if (JSON.stringify(metadataRecord[fieldKey]) === JSON.stringify(fieldValue)) {
                     continue;
                 }
-                document.metadata[fieldKey] = fieldValue;
+                metadataRecord[fieldKey] = fieldValue;
                 changedFields.push(fieldKey);
             }
             try {
-                applyRegisteredItemFieldDefaultsAndValidation(document.metadata, getActiveExtensionRegistrations());
+                applyRegisteredItemFieldDefaultsAndValidation(metadataRecord, getActiveExtensionRegistrations());
             }
             catch (error) {
                 throw new PmCliError(error instanceof Error ? error.message : "Invalid extension item field values", EXIT_CODE.USAGE);
@@ -1840,11 +1606,11 @@ export async function runUpdate(id, options, global) {
         },
     });
     return {
-        item: result.item,
+        item: toItemRecord(result.item),
         changed_fields: result.changedFields,
         warnings: [...parentReferenceWarnings, ...result.warnings],
         ...(options.allowAuditUpdate === true || options.allowAuditDepUpdate === true ? { audit_update: true } : {}),
     };
 }
 //# sourceMappingURL=update.js.map
-//# debugId=98e2bc37-91cc-5340-b212-da1076fc5857
+//# debugId=94e19c77-3288-5a43-a8b2-6b9f15d4f234