@unbrained/pm-cli 2026.8.9 → 2026.8.10

package/dist/sdk/governance/provenance-health.js

@@ -4,10 +4,26 @@
  * Reads bounded, privacy-safe provenance resolver outcomes for health checks.
  */
 
-!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]="68d4d540-a878-57f1-b2ae-00b111f94b43")}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]="60154e1b-8348-5b6b-badf-e76bba43bef8")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEFAULT_PROVENANCE_HISTORY_BYTE_LIMIT = 8_388_608;
+const ATTEMPTED_PROVENANCE_OUTCOME_STATUSES = new Set(["resolved", "failed"]);
+const INVALID_PROVENANCE_VALUE_CLASSIFIERS = [
+    {
+        kind: "boolean",
+        matches: (value) => typeof value === "boolean" ||
+            (typeof value === "string" && /^(?:true|false)$/iu.test(value.trim())),
+    },
+    {
+        kind: "single_digit",
+        matches: (value) => (typeof value === "number" &&
+            Number.isInteger(value) &&
+            value >= 0 &&
+            value <= 9) ||
+            (typeof value === "string" && /^\d$/u.test(value.trim())),
+    },
+];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -58,22 +74,44 @@ function parseHistoryEntry(line) {
         return null;
     }
 }
-function collectResolverOutcomes(entry, aggregates) {
+function collectResolverOutcomes(entry, aggregates, invalidValues) {
+    const harness = typeof entry.agent_harness === "string" ? entry.agent_harness : undefined;
+    if (harness === undefined)
+        return;
+    const provenance = isRecord(entry.agent_provenance)
+        ? entry.agent_provenance
+        : {};
+    Object.entries(provenance).forEach(([dimension, observation]) => {
+        if (!isRecord(observation))
+            return;
+        const kind = INVALID_PROVENANCE_VALUE_CLASSIFIERS.find((classifier) => classifier.matches(observation.value))?.kind;
+        if (!kind)
+            return;
+        const key = `${harness}\0${dimension}\0${kind}`;
+        const aggregate = invalidValues.get(key) ?? {
+            harness,
+            dimension,
+            kind,
+            count: 0,
+        };
+        aggregate.count += 1;
+        invalidValues.set(key, aggregate);
+    });
     if (!isRecord(entry.context))
         return;
     const outcomes = entry.context.agent_provenance_outcomes;
-    if (!isRecord(outcomes) || typeof entry.agent_harness !== "string")
+    if (!isRecord(outcomes))
         return;
-    for (const [dimension, rawOutcome] of Object.entries(outcomes)) {
+    Object.entries(outcomes).forEach(([dimension, rawOutcome]) => {
         if (!isRecord(rawOutcome) || typeof rawOutcome.resolver !== "string") {
-            continue;
+            return;
         }
-        if (rawOutcome.status !== "resolved" && rawOutcome.status !== "failed") {
-            continue;
+        if (!ATTEMPTED_PROVENANCE_OUTCOME_STATUSES.has(String(rawOutcome.status))) {
+            return;
         }
-        const key = `${entry.agent_harness}\0${dimension}\0${rawOutcome.resolver}`;
+        const key = `${harness}\0${dimension}\0${rawOutcome.resolver}`;
         const aggregate = aggregates.get(key) ?? {
-            harness: entry.agent_harness,
+            harness,
             dimension,
             resolver: rawOutcome.resolver,
             attempts: 0,
@@ -83,9 +121,9 @@ function collectResolverOutcomes(entry, aggregates) {
         if (rawOutcome.status === "resolved")
             aggregate.successes += 1;
         aggregates.set(key, aggregate);
-    }
+    });
 }
-function collectHistoryContent(content, aggregates, eventLimit, initialEventsRead) {
+function collectHistoryContent(content, aggregates, invalidValues, eventLimit, initialEventsRead) {
     let eventsRead = initialEventsRead;
     for (const line of content.split("\n")) {
         if (line.trim().length === 0)
@@ -95,13 +133,14 @@ function collectHistoryContent(content, aggregates, eventLimit, initialEventsRea
         eventsRead += 1;
         const entry = parseHistoryEntry(line);
         if (entry)
-            collectResolverOutcomes(entry, aggregates);
+            collectResolverOutcomes(entry, aggregates, invalidValues);
     }
     return { eventsRead, truncated: false };
 }
 /** Scan immutable history without failing over malformed streams owned by integrity checks. */
 export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000) {
     const aggregates = new Map();
+    const invalidValues = new Map();
     let eventsRead = 0;
     let bytesRead = 0;
     let truncated = false;
@@ -110,7 +149,7 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
         if (history === null)
             continue;
         bytesRead += history.bytesRead;
-        const collected = collectHistoryContent(history.content, aggregates, eventLimit, eventsRead);
+        const collected = collectHistoryContent(history.content, aggregates, invalidValues, eventLimit, eventsRead);
         eventsRead = collected.eventsRead;
         if (collected.truncated) {
             truncated = true;
@@ -124,16 +163,23 @@ export async function scanProvenanceResolverHealth(pmRoot, eventLimit = 10_000)
     const outcomes = [...aggregates.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
         left.dimension.localeCompare(right.dimension) ||
         left.resolver.localeCompare(right.resolver));
+    const invalidValueFindings = [...invalidValues.values()].sort((left, right) => left.harness.localeCompare(right.harness) ||
+        left.dimension.localeCompare(right.dimension) ||
+        left.kind.localeCompare(right.kind));
     return {
         outcomes,
+        invalid_values: invalidValueFindings,
         warnings: truncated
             ? []
-            : outcomes
-                .filter((outcome) => outcome.attempts > 0 && outcome.successes === 0)
-                .map((outcome) => `provenance_resolver_zero_success:${outcome.harness}:${outcome.dimension}:${outcome.resolver}:${String(outcome.attempts)}`),
+            : [
+                ...outcomes
+                    .filter((outcome) => outcome.attempts > 0 && outcome.successes === 0)
+                    .map((outcome) => `provenance_resolver_zero_success:${outcome.harness}:${outcome.dimension}:${outcome.resolver}:${String(outcome.attempts)}`),
+                ...invalidValueFindings.map((finding) => `provenance_value_domain_invalid:${finding.harness}:${finding.dimension}:${finding.kind}:${String(finding.count)}`),
+            ],
         events_read: eventsRead,
         truncated,
     };
 }
 //# sourceMappingURL=provenance-health.js.map
-//# debugId=68d4d540-a878-57f1-b2ae-00b111f94b43
+//# debugId=60154e1b-8348-5b6b-badf-e76bba43bef8

package/dist/sdk/governance/validate-item-reader.d.ts

@@ -0,0 +1,13 @@
+import type { ItemMetadata, PmSettings } from "../../types/index.js";
+/** Item projection accepted by validate checks; body is read only for strict drift verification. */
+export type ValidateItem = ItemMetadata & {
+    body: string;
+};
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export declare function readValidateItems(params: {
+    includeBody: boolean;
+    pmRoot: string;
+    settings: PmSettings;
+    typeToFolder: Record<string, string>;
+    warnings: string[];
+}): Promise<ValidateItem[]>;

package/dist/sdk/governance/validate-item-reader.js

@@ -0,0 +1,18 @@
+/**
+ * @module sdk/governance/validate-item-reader
+ *
+ * Selects the least expensive authoritative item projection required by a
+ * validation run.
+ */
+
+!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]="896ffe11-2cf1-5de0-8d07-5585d4f30c94")}catch(e){}}();
+import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
+/** Load collections for normal checks and add bodies only when history hashes must be verified. */
+export async function readValidateItems(params) {
+    if (params.includeBody) {
+        return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+    }
+    return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+}
+//# sourceMappingURL=validate-item-reader.js.map
+//# debugId=896ffe11-2cf1-5de0-8d07-5585d4f30c94

package/dist/sdk/governance/validate.d.ts

@@ -1,17 +1,17 @@
 import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import type { GlobalOptions } from "../../core/shared/command-types.js";
-import { listAllItemMetadataWithBody } from "../../core/store/item-store.js";
 import { type CloseReasonBackfillRow, type EstimateBackfillRow, type StaleLinkPruneRow, type TerminalParentFixRow, type ValidateFixRecord } from "../../core/validate/fix-planning.js";
 import { type DuplicateIssueCode } from "../../core/governance/issue-codes.js";
 import { type MissingFieldOccurrence } from "../../core/validate/missing-by-type.js";
 import type { ValidateMetadataProfile, ValidateMetadataRequiredField } from "../../types/index.js";
 import { type OutputProjectionDeclaration } from "../output-projection.js";
 import { type RelationshipKindRegistry } from "../relationships.js";
+import { type ValidateItem } from "./validate-item-reader.js";
 type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version" | "storage_integrity";
 type ValidateStatus = "ok" | "warn" | "error";
 type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
 type ValidateFileScanMode = "default" | "tracked-all" | "tracked-all-strict";
-type ItemWithBody = Awaited<ReturnType<typeof listAllItemMetadataWithBody>>[number];
+type ItemWithBody = ValidateItem;
 type OrphanedPathClassification = "docs_unowned" | "tests_unowned" | "source_unowned" | "unlinked_existing";
 declare const LIFECYCLE_PATTERN_FIELD_KEYS: readonly ["blocked_reason", "resolution", "actual_result"];
 type LifecyclePatternFieldKey = (typeof LIFECYCLE_PATTERN_FIELD_KEYS)[number];

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]="f4fe9337-9b1c-590f-9071-d685559bb7b9")}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";
@@ -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,7 +2100,10 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     }
     const pendingMergeReceipts = gitWorkspaceRoot === null
         ? []
-        : await listMergeReceipts(gitWorkspaceRoot, { includeLossless: true });
+        : 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}`);
@@ -2262,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) {
@@ -2337,4 +2346,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=f4fe9337-9b1c-590f-9071-d685559bb7b9
+//# debugId=b5b7e497-f067-5504-9ffa-fd177997c518

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]="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