@unbrained/pm-cli 2026.8.8 → 2026.8.10

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="f8048210-9e9f-585b-b0df-a34eca521cc3")}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]="b5b7e497-f067-5504-9ffa-fd177997c518")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -23,7 +23,6 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { CURRENT_ITEM_FORMAT_VERSION, effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { partitionFixesByGrant, planCloseReasonBackfillFixes, planEstimateBackfillFixes, planResolutionBackfillFixes, planStaleLinkPruneFixes, planTerminalParentFixes, resolveGrantedFixScopes, toFixOutputRow, } from "../../core/validate/fix-planning.js";
@@ -35,7 +34,7 @@ import { buildMissingLinkedPathRows, summarizeMissingLinkedPathRows, } from "../
 import { assertProjectionModeChoice, } from "../output-projection.js";
 import { collectDanglingDependencyReferences } from "../graph/assembly.js";
 import { auditMergeAttributeFence, auditMergeDriverConfiguration, findGitWorkspaceRoot, resolveProjectMergeTypeFolders, } from "../merge/install.js";
-import { listMergeReceipts } from "../merge/receipts.js";
+import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
 import { scanStorageIntegrity } from "./storage-integrity.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { scanHistoryAuthorAttribution } from "../author-attribution.js";
@@ -43,6 +42,7 @@ import { createRelationshipKindRegistry, } from "../relationships.js";
 import { runDocs } from "../docs.js";
 import { runFiles } from "../files.js";
 import { extractReferencedPmItemIdsFromCommand } from "../test/linked-command-detection.js";
+import { readValidateItems, } from "./validate-item-reader.js";
 const FILE_SCAN_DIRECTORIES = ["src", "tests", "docs"];
 const FILE_SCAN_ROOT_FILES = [
     "README.md",
@@ -2100,9 +2100,13 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     }
     const pendingMergeReceipts = gitWorkspaceRoot === null
         ? []
-        : await listMergeReceipts(gitWorkspaceRoot);
-    if (pendingMergeReceipts.length > 0) {
-        warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeReceipts.length}`);
+        : await listMergeReceipts(gitWorkspaceRoot, {
+            includeLossless: true,
+            pmRoot,
+        });
+    const { pendingDecisions: pendingMergeDecisions, lossless: losslessMergeReceipts, } = partitionMergeReceipts(pendingMergeReceipts);
+    if (pendingMergeDecisions.length > 0) {
+        warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeDecisions.length}`);
     }
     return {
         check: {
@@ -2115,9 +2119,13 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
                 ...scan,
                 merge_fence: fenceAudit,
                 merge_driver_configuration: mergeDriverAudit,
-                pending_merge_decision_count: pendingMergeReceipts.length,
+                pending_merge_decision_count: pendingMergeDecisions.length,
                 pending_merge_decision_items: [
-                    ...new Set(pendingMergeReceipts.map((receipt) => receipt.item_id)),
+                    ...new Set(pendingMergeDecisions.map((receipt) => receipt.item_id)),
+                ].sort((left, right) => left.localeCompare(right)),
+                lossless_merge_receipt_count: losslessMergeReceipts.length,
+                lossless_merge_receipt_items: [
+                    ...new Set(losslessMergeReceipts.map((receipt) => receipt.item_id)),
                 ].sort((left, right) => left.localeCompare(right)),
                 tracked_runtime_cache: {
                     tracker_relative_root: trackedRuntimeCache.tracker_relative_root,
@@ -2257,9 +2265,15 @@ export async function runValidate(options, global, services = {}) {
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
-    const itemReadWarnings = [];
-    const items = await listAllItemMetadataWithBody(pmRoot, settings.item_format, typeRegistry.type_to_folder, itemReadWarnings, settings.schema);
     const requestedChecks = resolveRequestedChecks(options);
+    const itemReadWarnings = [];
+    const items = await readValidateItems({
+        includeBody: requestedChecks.has("history_drift"),
+        pmRoot,
+        settings,
+        typeToFolder: typeRegistry.type_to_folder,
+        warnings: itemReadWarnings,
+    });
     if (requestedChecks.has("history_drift")) {
         const authorAttribution = await scanHistoryAuthorAttribution(pmRoot);
         if (authorAttribution.actionable_unknown_event_count > 0) {
@@ -2332,4 +2346,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=f8048210-9e9f-585b-b0df-a34eca521cc3
+//# debugId=b5b7e497-f067-5504-9ffa-fd177997c518

package/dist/sdk/governance.d.ts

@@ -12,4 +12,5 @@ export { runUpgrade, type UpgradeCliResult, type UpgradeCommandOptions, type Upg
 export * from "./governance/validate.js";
 export * from "./author-attribution.js";
 export * from "./mutation-guard.js";
+export * from "./governance/provenance-health.js";
 export * from "./similarity.js";

package/dist/sdk/governance.js

@@ -4,7 +4,7 @@
  * Provides validation, health, integrity, and mutation-policy primitives.
  */
 
-!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]="708c1c46-ce32-56ff-812f-71f825ad7ec4")}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]="8e8c2de1-7bff-57c6-8e71-9c27e9e76eaa")}catch(e){}}();
 export * from "./governance/gc.js";
 export * from "./governance/health.js";
 export { runReindex, } from "./governance/reindex.js";
@@ -14,6 +14,7 @@ export { runUpgrade, } from "./governance/upgrade.js";
 export * from "./governance/validate.js";
 export * from "./author-attribution.js";
 export * from "./mutation-guard.js";
+export * from "./governance/provenance-health.js";
 export * from "./similarity.js";
 //# sourceMappingURL=governance.js.map
-//# debugId=708c1c46-ce32-56ff-812f-71f825ad7ec4
+//# debugId=8e8c2de1-7bff-57c6-8e71-9c27e9e76eaa

package/dist/sdk/graph/assembly.d.ts

@@ -127,7 +127,11 @@ export interface WorkspaceRelationshipAssembly {
     dangling: DanglingDependencyReferenceSummary;
     /** Raw same-identity duplicated dependency rows found before graph dedup. */
     duplicateRows: DuplicateDependencyRow[];
+    /** Raw legacy alias rows grouped by accepted spelling before graph canonicalization. */
+    legacyAliasCounts: Record<string, number>;
 }
+/** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
+export declare function collectLegacyDependencyAliasCounts(items: readonly DependencyReferenceHolder[], registry?: RelationshipKindRegistry): Record<string, number>;
 /**
  * Build the shared workspace relationship graph including missing placeholder
  * nodes. One assembly serves every bounded query in an invocation — dependency

package/dist/sdk/graph/assembly.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8368a519-4c09-540e-b0fb-f74cfdc1d7b2")}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]="62ec8e0e-658e-5a32-b458-439d5ffd1229")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { RelationshipGraph, createRelationshipKindRegistry, } from "../relationships.js";
 import { isExternalDependencySourceKind } from "../dependency-provenance.js";
@@ -191,6 +191,25 @@ export function collectExternalDependencyTargetIds(items) {
     }
     return [...targets.values()].sort((left, right) => left.localeCompare(right));
 }
+/** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
+export function collectLegacyDependencyAliasCounts(items, registry = resolveWorkspaceRelationshipKindRegistry()) {
+    const counts = {};
+    for (const item of items) {
+        for (const dependency of item.dependencies ?? []) {
+            if (typeof dependency !== "object" || dependency === null)
+                continue;
+            const rawKind = dependency.kind;
+            if (typeof rawKind !== "string")
+                continue;
+            const normalized = rawKind.trim().toLowerCase().replaceAll("-", "_");
+            const definition = registry.resolve(rawKind);
+            if (definition && normalized !== definition.kind) {
+                counts[normalized] = (counts[normalized] ?? 0) + 1;
+            }
+        }
+    }
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
 /**
  * Build the shared workspace relationship graph including missing placeholder
  * nodes. One assembly serves every bounded query in an invocation — dependency
@@ -277,7 +296,8 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
         missingIdSet: new Set(missingIds.map((id) => id.toLowerCase())),
         dangling,
         duplicateRows: collectDuplicateDependencyRows(safeItems, isTerminal),
+        legacyAliasCounts: collectLegacyDependencyAliasCounts(safeItems, relationshipRegistry),
     };
 }
 //# sourceMappingURL=assembly.js.map
-//# debugId=8368a519-4c09-540e-b0fb-f74cfdc1d7b2
+//# debugId=62ec8e0e-658e-5a32-b458-439d5ffd1229

package/dist/sdk/graph/run.d.ts

@@ -194,6 +194,8 @@ export interface GraphAuditResult {
     affected_subjects_by_code: Record<string, number>;
     /** Structural coverage metrics computed during the audit. */
     profile: RelationshipAuditReport["profile"];
+    /** Stored legacy relationship aliases grouped by spelling; canonical graph counts remain in profile. */
+    legacy_alias_counts?: Record<string, number>;
     /** Ordered findings with bounded evidence samples; absent with summary. */
     findings?: RelationshipAuditReport["findings"];
     /** Signed change since the persisted census baseline; absent when no baseline exists. */

package/dist/sdk/graph/run.js

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

package/dist/sdk/index.d.ts

@@ -17,6 +17,10 @@ export { SNAPSHOT_SCHEMA, createWorkspaceSnapshot, deleteWorkspaceSnapshot, insp
 export { flushTelemetryQueue } from "./telemetry-flush.js";
 export { EXECUTABLE_COMMAND_ALIASES, applyBootstrapPagerPolicy, coalesceRepeatedListFlags, listAliasPluralKeys, mergeLinkedTestTwoTokenEntries, normalizeBootstrapInvocation, normalizeLegacyExtensionActionSyntax, parseBootstrapCommandName, parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapTypeValue, stripGlobalBootstrapTokens, type BootstrapGlobalOptions, type BootstrapHelpRequest, type BootstrapInvocationNormalizationResult, type BootstrapNormalizationEvent, } from "./cli-bootstrap.js";
 export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./command-line.js";
+export * from "./agent/command-recovery.js";
+export * from "./agent/command-suggestions.js";
+export * from "./agent/item-addressing.js";
+export * from "./agent/create-option-policy.js";
 export { runGc, type GcCheckpointsSummary, type GcLocksSummary, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, type HealthCheck, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, type ValidateCheck, type ValidateCountsFixesSummary, type ValidateCountsResult, type ValidateFixesSummary, type ValidateMutationServices, } from "./governance/validate.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ae84c7af-bfa7-577d-b9f3-2bd9450d5755")}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]="99d427a5-1f09-5ca4-8c1f-8b9d54bfd2f2")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, normalizeAnnotationTransportOptions, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -18,6 +18,10 @@ export { SNAPSHOT_SCHEMA, createWorkspaceSnapshot, deleteWorkspaceSnapshot, insp
 export { flushTelemetryQueue } from "./telemetry-flush.js";
 export { EXECUTABLE_COMMAND_ALIASES, applyBootstrapPagerPolicy, coalesceRepeatedListFlags, listAliasPluralKeys, mergeLinkedTestTwoTokenEntries, normalizeBootstrapInvocation, normalizeLegacyExtensionActionSyntax, parseBootstrapCommandName, parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapTypeValue, stripGlobalBootstrapTokens, } from "./cli-bootstrap.js";
 export { quoteCommandArg, quoteWindowsCommandArg, renderPmCommand, } from "./command-line.js";
+export * from "./agent/command-recovery.js";
+export * from "./agent/command-suggestions.js";
+export * from "./agent/item-addressing.js";
+export * from "./agent/create-option-policy.js";
 export { runGc, } from "./governance/gc.js";
 export { _testOnlyHealthCommand, runHealth, } from "./governance/health.js";
 export { _testOnlyValidateCommand, projectValidateCounts, runValidate, } from "./governance/validate.js";
@@ -141,4 +145,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=ae84c7af-bfa7-577d-b9f3-2bd9450d5755
+//# debugId=99d427a5-1f09-5ca4-8c1f-8b9d54bfd2f2

package/dist/sdk/lifecycle/close.js

@@ -4,9 +4,9 @@
  * Implements the pm close command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7d90aefe-43ba-5b24-8982-07e37e8d46a9")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="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 } 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;
@@ -137,14 +137,19 @@ function findActiveChildIds(items, parentId, statusRegistry) {
         .sort((left, right) => left.localeCompare(right));
 }
 function findAutoUnblockCandidates(items, closedId, statusRegistry) {
-    const itemsById = new Map(items.map((item) => [item.id, item]));
+    const itemsById = new Map(items.map((item) => [item.id.trim().toLowerCase(), item]));
+    const blockerIdsByItem = indexBlockedByIds(items);
+    const normalizedClosedId = closedId.trim().toLowerCase();
     const blockedStatuses = statusRegistry.blocked_statuses;
     return items
         .filter((item) => blockedStatuses.has(item.status))
-        .map((item) => ({ item, blockerIds: collectBlockedByIds(item) }))
-        .filter(({ blockerIds }) => blockerIds.includes(closedId))
+        .map((item) => ({
+        item,
+        blockerIds: blockerIdsByItem.get(item.id.trim().toLowerCase()),
+    }))
+        .filter(({ blockerIds }) => blockerIds.includes(normalizedClosedId))
         .filter(({ blockerIds }) => blockerIds.every((blockerId) => {
-        if (blockerId === closedId) {
+        if (blockerId === normalizedClosedId) {
             return true;
         }
         const blocker = itemsById.get(blockerId);
@@ -171,7 +176,7 @@ async function autoUnblockResolvedDependents(pmRoot, settings, items, closedId,
                     const dependencies = document.metadata.dependencies ?? [];
                     /* c8 ignore stop */
                     const remainingDependencies = dependencies.filter((dependency) => {
-                        const dependencyId = dependency.id.trim();
+                        const dependencyId = dependency.id.trim().toLowerCase();
                         return (dependency.kind !== "blocked_by" ||
                             !candidate.blocker_ids.includes(dependencyId));
                     });
@@ -254,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") {
@@ -315,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 ||
@@ -423,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,
@@ -450,4 +458,4 @@ export function runClose(id, closeReasonText, options, global) {
     return closeItem(id, closeReasonText, options, global);
 }
 //# sourceMappingURL=close.js.map
-//# debugId=7d90aefe-43ba-5b24-8982-07e37e8d46a9
+//# debugId=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]="93dc76a3-f205-5a44-85bd-5a6fad80c8d4")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="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,8 +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"];
@@ -188,17 +190,10 @@ function parseDependencies(raw, nowValue, prefix, fallbackAuthor) {
     });
     return { values, explicitEmpty: false };
 }
-const DEPENDENCY_KIND_INPUT_ALIASES = {
-    "blocked-by": "blocked_by",
-    depends_on: "blocked_by",
-    "depends-on": "blocked_by",
-};
 function normalizeDependencyKindInput(raw) {
-    if (typeof raw !== "string") {
-        return raw;
-    }
-    const alias = DEPENDENCY_KIND_INPUT_ALIASES[raw.toLowerCase()];
-    return alias ?? raw;
+    return typeof raw === "string"
+        ? (resolveCanonicalRelationshipKind(raw) ?? raw.trim())
+        : raw;
 }
 function looksLikeStructuredEntry(raw, keys) {
     if (raw.startsWith("```") || raw.includes("\n")) {
@@ -521,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;
     }
@@ -619,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));
@@ -1036,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) {
@@ -1062,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;
         }
@@ -1095,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) {
@@ -1316,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.`,
     ];
@@ -1335,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}"`;
@@ -1559,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>`);
@@ -1578,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({
@@ -1625,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,
@@ -1657,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);
@@ -1794,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.
@@ -1841,4 +1888,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=93dc76a3-f205-5a44-85bd-5a6fad80c8d4
+//# debugId=ffa56c1a-d98c-566a-81c5-4ad5608aa26c

package/dist/sdk/lifecycle/plan.js

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