@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/cli/commander-usage.js

@@ -1,14 +1,16 @@
 
-!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]="042ecf17-9265-5496-bbee-4e7a07371618")}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]="78ae2dad-a000-57be-9492-caea26a412ef")}catch(e){}}();
 import { pathExists, resolveItemTypeRegistry, EXIT_CODE, getSettingsPath, resolvePmRoot, readSettings, getActiveExtensionRegistrations, runActiveServiceOverride, levenshteinDistanceWithinLimit, } from "../sdk/runtime-primitives.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { PM_CORE_COMMAND_NAMES, resolveSubcommandFlagContractsForCommand, } from "../sdk/cli-contracts.js";
 import { formatCommanderErrorForDisplay, formatCommanderErrorForJson, projectLeanErrorEnvelope, } from "./error-guidance.js";
 import { normalizeHelpCommandPath } from "./help-content.js";
 import { getCommandPath } from "./registration-helpers.js";
-import { EXECUTABLE_COMMAND_ALIASES, normalizeBootstrapInvocation, parseBootstrapHelpRequest, parseBootstrapGlobalOptions, parseBootstrapCommandName, } from "./bootstrap-args.js";
+import { EXECUTABLE_COMMAND_ALIASES, findBootstrapCommandTokenIndex, normalizeBootstrapInvocation, parseBootstrapHelpRequest, parseBootstrapGlobalOptions, parseBootstrapCommandName, } from "./bootstrap-args.js";
 import { extractProvidedOptionFlags, normalizeLongFlag, renderPmCommand, } from "./argv-utils.js";
 import { normalizeExtensionNameForMatch } from "./commands/extension/shared.js";
+import { rankCommandPaths } from "../sdk/agent/command-suggestions.js";
+import { renderMissingOptionRetry } from "../sdk/agent/command-recovery.js";
 /** Supported values accepted by the builtin type help contract. */
 export const BUILTIN_TYPE_HELP_VALUES = BUILTIN_ITEM_TYPE_VALUES.join("|");
 const OPTIONAL_PACKAGE_INSTALL_HINTS = {
@@ -52,6 +54,23 @@ const SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS = {
         "--tag": ["--tags"],
     },
 };
+const SCHEMA_SUBCOMMAND_VALUES = [
+    "add-field",
+    "add-status",
+    "add-type",
+    "apply-preset",
+    "list",
+    "list-fields",
+    "remap-status",
+    "remove-field",
+    "remove-status",
+    "remove-type",
+    "rename-field",
+    "rename-type",
+    "show",
+    "show-field",
+    "show-status",
+];
 function getSemanticUnknownOptionSuggestions(commandName, unknownOption) {
     const commandSuggestions = SEMANTIC_UNKNOWN_OPTION_SUGGESTIONS[commandName];
     if (!commandSuggestions) {
@@ -333,9 +352,17 @@ function findOtherCommandsForFlag(unknownOption, currentCommand) {
         return [];
     }
     const normalizedCurrent = currentCommand?.trim().toLowerCase();
+    const currentFlags = new Set(collectKnownLongFlags(normalizedCurrent));
     return commands
         .filter((command) => command !== normalizedCurrent)
-        .slice(0, 3);
+        .map((command) => ({
+        command,
+        sharedFlagCount: collectKnownLongFlags(command).filter((flag) => currentFlags.has(flag)).length,
+    }))
+        .sort((left, right) => left.sharedFlagCount !== right.sharedFlagCount
+        ? right.sharedFlagCount - left.sharedFlagCount
+        : left.command.localeCompare(right.command))
+        .map(({ command }) => command);
 }
 function rewriteUnknownOptionArgv(argv, unknownOption, replacementFlag) {
     for (let index = 0; index < argv.length; index += 1) {
@@ -388,9 +415,14 @@ function scoreRuntimeCommandCandidates(params) {
         .map(([commandPath]) => commandPath);
 }
 function resolveUnknownCommandCandidates(params) {
+    const semanticCandidates = rankCommandPaths(params.commandPaths, params.primaryToken);
     const rankedCandidates = scoreRuntimeCommandCandidates(params);
     const installedPackageCandidates = collectInstalledPackageCommandPathHints(params.primaryToken, params.extensionDescriptors).filter((commandPath) => params.commandPaths.includes(commandPath));
-    return dedupeStrings([...rankedCandidates, ...installedPackageCandidates]);
+    return dedupeStrings([
+        ...semanticCandidates,
+        ...rankedCandidates,
+        ...installedPackageCandidates,
+    ]);
 }
 function resolveUnknownCommandFallbacks(commandPaths) {
     const topLevel = [
@@ -556,15 +588,42 @@ function resolveSuggestedRetryForMissingOption(message, invocationArgv) {
     if (!requiredOptionToken?.startsWith("--")) {
         return undefined;
     }
-    const hasFlag = invocationArgv.some((token) => token === requiredOptionToken ||
-        token.startsWith(`${requiredOptionToken}=`));
-    return hasFlag
-        ? undefined
-        : renderAttemptedCommand([
-            ...invocationArgv,
-            requiredOptionToken,
-            "<value>",
-        ]);
+    const commandName = parseBootstrapCommandName(invocationArgv);
+    if (!commandName) {
+        return undefined;
+    }
+    return renderMissingOptionRetry(invocationArgv, commandName, [
+        requiredOptionToken,
+    ]);
+}
+function resolveSplitSchemaSubcommand(message, invocationArgv) {
+    if (!/too many arguments/i.test(message)) {
+        return undefined;
+    }
+    if (parseBootstrapCommandName(invocationArgv) !== "schema") {
+        return undefined;
+    }
+    const schemaIndex = findBootstrapCommandTokenIndex(invocationArgv);
+    const verb = invocationArgv[schemaIndex + 1]?.trim().toLowerCase();
+    const noun = invocationArgv[schemaIndex + 2]?.trim().toLowerCase();
+    if (!verb || !noun) {
+        return undefined;
+    }
+    const joined = `${verb}-${noun}`;
+    if (!SCHEMA_SUBCOMMAND_VALUES.includes(joined)) {
+        return undefined;
+    }
+    const rewritten = [
+        ...invocationArgv.slice(0, schemaIndex + 1),
+        joined,
+        ...invocationArgv.slice(schemaIndex + 3),
+    ];
+    return {
+        unknownSubcommandPath: "schema",
+        unknownSubcommandToken: `${verb} ${noun}`,
+        unknownSubcommandAllowedValues: [...SCHEMA_SUBCOMMAND_VALUES],
+        suggestedRetryCommand: renderAttemptedCommand(rewritten),
+    };
 }
 /** Implements resolve commander usage context for the public runtime surface of this module. */
 export async function resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
@@ -580,7 +639,10 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
     const allowedTypes = await resolveAllowedTypesForUsage(bootstrapGlobal);
     const unknownCommandGuidance = buildUnknownCommandGuidanceFromRuntime(message, rootProgram, extensionDescriptors);
     const unknownOption = resolveUnknownOptionSuggestions(message, commandName);
-    const suggestedRetryCommand = resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ?? resolveSuggestedRetryForMissingOption(message, invocationArgv);
+    const splitSchemaSubcommand = resolveSplitSchemaSubcommand(message, invocationArgv);
+    const suggestedRetryCommand = splitSchemaSubcommand?.suggestedRetryCommand ??
+        resolveSuggestedRetryForUnknownOption(invocationArgv, unknownOption.match, unknownOption.suggestions) ??
+        resolveSuggestedRetryForMissingOption(message, invocationArgv);
     return {
         message,
         commandName,
@@ -590,9 +652,14 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
         providedOptionFlags,
         unknownOptionSuggestions: unknownOption.suggestions,
         unknownOptionOtherCommands: unknownOption.otherCommands.length > 0
-            ? unknownOption.otherCommands
+            ? unknownOption.otherCommands.slice(0, 12)
+            : undefined,
+        unknownOptionOtherCommandsTotal: unknownOption.otherCommands.length > 0
+            ? unknownOption.otherCommands.length
             : undefined,
+        unknownOptionOtherCommandsTruncated: unknownOption.otherCommands.length > 12 || undefined,
         suggestedRetryCommand,
+        ...splitSchemaSubcommand,
         ...unknownCommandGuidance,
         ...guidanceOverrides,
     };
@@ -600,7 +667,7 @@ export async function resolveCommanderUsageContext(error, rootProgram, extension
 /** Implements format commander usage message for the public runtime surface of this module. */
 export async function formatCommanderUsageMessage(error, rootProgram, extensionDescriptors, guidanceOverrides = {}) {
     const usageContext = await resolveCommanderUsageContext(error, rootProgram, extensionDescriptors, guidanceOverrides);
-    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, suggestedRetryCommand, failedExtensions, } = usageContext;
+    const { message, commandName, allowedTypes, unknownCommandExamples, unknownCommandNextSteps, attemptedCommand, normalizedInvocationArgs, providedOptionFlags, unknownOptionSuggestions, unknownOptionOtherCommands, unknownOptionOtherCommandsTotal, unknownOptionOtherCommandsTruncated, unknownSubcommandPath, unknownSubcommandToken, unknownSubcommandAllowedValues, suggestedRetryCommand, failedExtensions, } = usageContext;
     const formatted = formatCommanderErrorForDisplay(message, commandName, allowedTypes, {
         unknownCommandExamples,
         unknownCommandNextSteps,
@@ -609,6 +676,11 @@ export async function formatCommanderUsageMessage(error, rootProgram, extensionD
         providedOptionFlags,
         unknownOptionSuggestions,
         unknownOptionOtherCommands,
+        unknownOptionOtherCommandsTotal,
+        unknownOptionOtherCommandsTruncated,
+        unknownSubcommandPath,
+        unknownSubcommandToken,
+        unknownSubcommandAllowedValues,
         suggestedRetryCommand,
         failedExtensions,
     });
@@ -633,6 +705,11 @@ export async function formatCommanderUsageJson(error, rootProgram, extensionDesc
         providedOptionFlags: usageContext.providedOptionFlags,
         unknownOptionSuggestions: usageContext.unknownOptionSuggestions,
         unknownOptionOtherCommands: usageContext.unknownOptionOtherCommands,
+        unknownOptionOtherCommandsTotal: usageContext.unknownOptionOtherCommandsTotal,
+        unknownOptionOtherCommandsTruncated: usageContext.unknownOptionOtherCommandsTruncated,
+        unknownSubcommandPath: usageContext.unknownSubcommandPath,
+        unknownSubcommandToken: usageContext.unknownSubcommandToken,
+        unknownSubcommandAllowedValues: usageContext.unknownSubcommandAllowedValues,
         suggestedRetryCommand: usageContext.suggestedRetryCommand,
         failedExtensions: usageContext.failedExtensions,
     });
@@ -647,4 +724,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=042ecf17-9265-5496-bbee-4e7a07371618
+//# debugId=78ae2dad-a000-57be-9492-caea26a412ef

package/dist/cli/error-guidance.d.ts

@@ -77,6 +77,16 @@ export interface CommanderGuidanceContext {
     unknownOptionSuggestions?: string[];
     /** Value that configures or reports unknown option other commands for this contract. */
     unknownOptionOtherCommands?: string[];
+    /** Complete number of commands accepting the unknown option. */
+    unknownOptionOtherCommandsTotal?: number;
+    /** Whether the structured command candidates reached their own ceiling. */
+    unknownOptionOtherCommandsTruncated?: boolean;
+    /** Command family whose positional subcommand was split into invalid tokens. */
+    unknownSubcommandPath?: string;
+    /** Rejected positional subcommand token or token sequence. */
+    unknownSubcommandToken?: string;
+    /** Complete declared subcommand vocabulary for the command family. */
+    unknownSubcommandAllowedValues?: string[];
     /** Value that configures or reports suggested retry command for this contract. */
     suggestedRetryCommand?: string;
     /** Installed extensions whose activation failed for this invocation. */

package/dist/cli/error-guidance.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]="d9d3d041-587b-5660-a909-d0759998248d")}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]="4d6caae5-76d6-5563-acb9-b435f8cdfe9c")}catch(e){}}();
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
 /** Compact an error envelope to fields that change the caller's next action. */
@@ -145,6 +145,16 @@ function normalizeRecoveryPayload(payload) {
     assignRecoveryStringArray(normalized, "missing", payload.missing);
     assignRecoveryStringArray(normalized, "missing_required_fields", payload.missing_required_fields);
     assignRecoveryStringArray(normalized, "suggested_flags", payload.suggested_flags);
+    assignRecoveryStringArray(normalized, "allowed_values", payload.allowed_values);
+    assignRecoveryStringArray(normalized, "candidate_commands", payload.candidate_commands);
+    if (typeof payload.candidate_commands_total === "number" &&
+        Number.isSafeInteger(payload.candidate_commands_total) &&
+        payload.candidate_commands_total >= 0) {
+        normalized.candidate_commands_total = payload.candidate_commands_total;
+    }
+    if (payload.candidate_commands_truncated === true) {
+        normalized.candidate_commands_truncated = true;
+    }
     assignRecoveryString(normalized, "suggested_retry", payload.suggested_retry);
     if (typeof payload.retry_after_ms === "number" &&
         Number.isSafeInteger(payload.retry_after_ms) &&
@@ -180,6 +190,14 @@ function renderRecoveryBundle(recovery) {
     appendRecoveryListLine(lines, "missing", normalized.missing, ", ");
     appendRecoveryListLine(lines, "missing_required_fields", normalized.missing_required_fields, ", ");
     appendRecoveryListLine(lines, "suggested_flags", normalized.suggested_flags, ", ");
+    appendRecoveryListLine(lines, "allowed_values", normalized.allowed_values, ", ");
+    appendRecoveryListLine(lines, "candidate_commands", normalized.candidate_commands, ", ");
+    if (typeof normalized.candidate_commands_total === "number") {
+        lines.push(`  candidate_commands_total: ${String(normalized.candidate_commands_total)}`);
+    }
+    if (normalized.candidate_commands_truncated === true) {
+        lines.push("  candidate_commands_truncated: true");
+    }
     appendRecoveryTextLine(lines, "suggested_retry", normalized.suggested_retry);
     if (typeof normalized.retry_after_ms === "number") {
         lines.push(`  retry_after_ms: ${normalized.retry_after_ms}`);
@@ -471,9 +489,7 @@ function buildLockConflictGuidance(rawMessage, message, context) {
         happened: message,
         required: "Wait for lock release, or use --force where supported if lock is stale and safe to override.",
         why: "Locking protects item files from concurrent write races.",
-        examples: [
-            "pm update pm-a1b2 --status in_progress --force",
-        ],
+        examples: ["pm update pm-a1b2 --status in_progress --force"],
     }), rawMessage, context);
 }
 function buildPmMissingRequiredOptionGuidance(rawMessage, message, context) {
@@ -797,32 +813,36 @@ function buildUnknownOptionGuidance(message, commandName, context) {
     if (!unknownOption) {
         return null;
     }
+    const guidanceContext = context ?? {};
     const optionName = unknownOption[1];
-    const suggestions = normalizeOptionFlags(context?.unknownOptionSuggestions);
-    const retryCommand = context?.suggestedRetryCommand;
+    const suggestions = normalizeOptionFlags(guidanceContext.unknownOptionSuggestions) ?? [];
+    const retryCommand = guidanceContext.suggestedRetryCommand;
     if (commandName === "update" &&
         (optionName === "--file" || optionName === "--doc")) {
         return buildUnsupportedUpdateOptionGuidance(optionName, context, suggestions);
     }
-    const otherCommands = normalizeContextList(context?.unknownOptionOtherCommands);
+    const otherCommands = normalizeContextList(guidanceContext.unknownOptionOtherCommands) ?? [];
+    const candidateTotal = guidanceContext.unknownOptionOtherCommandsTotal ??
+        otherCommands.length;
+    const proseCommands = otherCommands.slice(0, 3);
+    const proseRemainder = candidateTotal - proseCommands.length;
+    let proseRemainderText = "";
+    if (proseRemainder > 0) {
+        proseRemainderText = ` and ${String(proseRemainder)} more command path(s)`;
+    }
     const nextSteps = [
         "Run command help to confirm the exact option contracts for this command path.",
-        ...(suggestions && suggestions.length > 0
-            ? [`Nearest supported options: ${suggestions.join(", ")}`]
-            : []),
-        ...(otherCommands && otherCommands.length > 0
-            ? [
-                `${optionName} is a valid option on: ${otherCommands.join(", ")}. If you meant one of those, run that command instead.`,
-            ]
-            : []),
-        ...(retryCommand
-            ? [`Replay with suggested correction: ${retryCommand}`]
-            : []),
-    ];
-    const examples = [
-        ...(retryCommand ? [retryCommand] : []),
-        `pm ${commandName ?? "<command>"} --help`,
-    ];
+        suggestions.length
+            ? `Nearest supported options: ${suggestions.join(", ")}`
+            : undefined,
+        proseCommands.length
+            ? `${optionName} is accepted by ${proseCommands.join(", ")}${proseRemainderText}. Inspect those command contracts only if you intended a different operation.`
+            : undefined,
+        retryCommand
+            ? `Replay with suggested correction: ${retryCommand}`
+            : undefined,
+    ].filter((entry) => typeof entry === "string");
+    const examples = [retryCommand, `pm ${commandName ?? "<command>"} --help`].filter((entry) => typeof entry === "string");
     return makeGuidanceMessage({
         code: "unknown_option",
         title: `Unknown option ${optionName}`,
@@ -832,7 +852,10 @@ function buildUnknownOptionGuidance(message, commandName, context) {
         examples,
         nextSteps,
         recovery: buildCommanderRecoveryPayload(context, {
-            suggested_flags: suggestions,
+            suggested_flags: suggestions.length > 0 ? suggestions : undefined,
+            candidate_commands: otherCommands,
+            candidate_commands_total: candidateTotal || undefined,
+            candidate_commands_truncated: guidanceContext.unknownOptionOtherCommandsTruncated,
         }),
     });
 }
@@ -884,6 +907,33 @@ function buildUnknownCommandGuidance(message, context) {
         recovery: buildCommanderRecoveryPayload(context),
     });
 }
+function buildUnknownSubcommandGuidance(context) {
+    const commandPath = context?.unknownSubcommandPath?.trim();
+    const token = context?.unknownSubcommandToken?.trim();
+    const allowed = normalizeContextList(context?.unknownSubcommandAllowedValues);
+    if (!commandPath || !token || !allowed) {
+        return null;
+    }
+    const retryCommand = context?.suggestedRetryCommand;
+    return makeGuidanceMessage({
+        code: "unknown_subcommand",
+        title: `Unknown ${commandPath} subcommand ${token}`,
+        happened: `The positional token sequence "${token}" is not a declared ${commandPath} subcommand.`,
+        required: `Use one of: ${allowed.join(", ")}.`,
+        why: "Subcommands are single positional tokens; multi-word action names use hyphens.",
+        examples: [
+            ...(retryCommand ? [retryCommand] : []),
+            `pm ${commandPath} --help`,
+        ],
+        nextSteps: retryCommand
+            ? [`Retry with the declared hyphenated action: ${retryCommand}`]
+            : ["Choose one value from recovery.allowed_values."],
+        recovery: buildCommanderRecoveryPayload(context, {
+            allowed_values: allowed,
+            suggested_retry: retryCommand,
+        }),
+    });
+}
 function buildLinkedTestValueNotQuotedGuidance(message, commandName, context) {
     if (!/too many arguments/i.test(message) || commandName !== "test") {
         return null;
@@ -990,6 +1040,7 @@ function buildCommanderErrorGuidance(rawMessage, commandName, allowedTypes, cont
         buildMissingRequiredArgumentGuidance(message, commandName, context) ??
         buildUnknownOptionGuidance(message, commandName, context) ??
         buildUnknownCommandGuidance(message, context) ??
+        buildUnknownSubcommandGuidance(context) ??
         buildLinkedTestValueNotQuotedGuidance(message, commandName, context) ??
         buildContextItemArgumentGuidance(message, commandName, context);
     if (guidance) {
@@ -1083,4 +1134,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=d9d3d041-587b-5660-a909-d0759998248d
+//# debugId=4d6caae5-76d6-5563-acb9-b435f8cdfe9c

package/dist/cli/help-json-payload.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]="a33bada3-c1a1-5343-8a77-51dc76dd5a11")}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]="42b9782e-2151-54b0-98ce-8c5ae810c424")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
 import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
@@ -9,6 +9,7 @@ import { parseBootstrapGlobalOptions, parseBootstrapHelpRequest, parseBootstrapC
 import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
 import { formatCommanderErrorForJson } from "./error-guidance.js";
 import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, } from "./commander-usage.js";
+import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
 function resolveCommandFromPathTokens(root, pathTokens) {
     if (pathTokens.length === 0) {
         return root;
@@ -303,6 +304,39 @@ function appendTypeOptionHelpLines(lines, typeDefinition) {
         }
     }
 }
+function buildCreatePolicyRequiredSets(commandName, typeDefinition) {
+    const progressive = commandName === "create"
+        ? new Set(["title", "type"])
+        : new Set();
+    const strict = new Set(progressive);
+    if (commandName === "create") {
+        for (const option of [
+            ...typeDefinition.required_create_fields,
+            ...typeDefinition.required_create_repeatables,
+        ]) {
+            strict.add(option);
+        }
+    }
+    return { progressive, strict };
+}
+function appendStrictCreatePolicyHelpLines(lines, typeDefinition, progressiveRequired, strictRequired) {
+    const progressive = new Set(progressiveRequired);
+    const strictOnly = strictRequired.filter((option) => !progressive.has(option));
+    const toFlags = (options) => options.length > 0
+        ? options
+            .map((option) => commandOptionFlagLabel("create", option))
+            .join(", ")
+        : "none";
+    lines.push(`  required in strict mode: ${toFlags(strictOnly)}`);
+    const explicitEmptyFlags = strictOnly
+        .map(resolveCreateExplicitEmptyFlag)
+        .filter((flag) => flag !== undefined);
+    lines.push(`  explicit empty assertion: ${explicitEmptyFlags.length > 0 ? explicitEmptyFlags.join(", ") : "none"}`);
+    if (["Reminder", "Meeting", "Event"].includes(typeDefinition.name)) {
+        lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");
+        lines.push("  strict parity remains available via --create-mode strict.");
+    }
+}
 function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
     const selectedTypeRaw = parseBootstrapTypeValue(argv);
     if (!selectedTypeRaw) {
@@ -317,16 +351,18 @@ function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
             `  active type values: ${allowed}`,
         ].join("\n");
     }
-    const baseRequired = commandName === "create"
-        ? new Set([
-            "title",
-            "description",
-            "type",
-            ...typeDefinition.required_create_fields,
-            ...typeDefinition.required_create_repeatables,
-        ])
-        : new Set();
-    const policyState = resolveCommandOptionPolicyState(typeDefinition, commandName, baseRequired);
+    const argumentTerminatorIndex = argv.indexOf("--");
+    const optionArgv = argumentTerminatorIndex < 0 ? argv : argv.slice(0, argumentTerminatorIndex);
+    const createModeTokenIndex = optionArgv.findIndex((token) => token === "--create-mode" || token.startsWith("--create-mode="));
+    const createModeToken = createModeTokenIndex < 0
+        ? undefined
+        : optionArgv[createModeTokenIndex]?.startsWith("--create-mode=")
+            ? optionArgv[createModeTokenIndex]?.slice("--create-mode=".length)
+            : optionArgv[createModeTokenIndex + 1];
+    const strictCreateMode = commandName === "create" && createModeToken?.toLowerCase() === "strict";
+    const requiredSets = buildCreatePolicyRequiredSets(commandName, typeDefinition);
+    const progressivePolicyState = resolveCommandOptionPolicyState(typeDefinition, commandName, requiredSets.progressive);
+    const policyState = resolveCommandOptionPolicyState(typeDefinition, commandName, strictCreateMode ? requiredSets.strict : requiredSets.progressive);
     const toFlags = (options) => options.length > 0
         ? options
             .map((option) => commandOptionFlagLabel(commandName, option))
@@ -339,10 +375,9 @@ function buildCreateUpdatePolicyHelpText(commandName, typeRegistry, argv) {
         `  disabled: ${toFlags(policyState.disabled)}`,
         `  hidden: ${toFlags(policyState.hidden)}`,
     ];
-    if (commandName === "create" &&
-        ["Reminder", "Meeting", "Event"].includes(typeDefinition.name)) {
-        lines.push("  schedule preset: --schedule-preset lightweight switches schedule artifacts to progressive required-option policy.");
-        lines.push("  strict parity remains available via --create-mode strict.");
+    if (commandName === "create") {
+        const strictPolicyState = resolveCommandOptionPolicyState(typeDefinition, commandName, requiredSets.strict);
+        appendStrictCreatePolicyHelpLines(lines, typeDefinition, progressivePolicyState.required, strictPolicyState.required);
     }
     appendTypeOptionHelpLines(lines, typeDefinition);
     if (policyState.errors.length > 0) {
@@ -376,4 +411,4 @@ export const _testOnly = {
     resolveCommandFromPathTokens,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=a33bada3-c1a1-5343-8a77-51dc76dd5a11
+//# debugId=42b9782e-2151-54b0-98ce-8c5ae810c424

package/dist/cli/main.js

@@ -3,7 +3,7 @@
  * @module cli/main
  */
 
-!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]="52c705ab-a5c4-5b94-b806-4eaac31b6e9c")}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]="80e9dea8-2bb3-50e7-b21e-50ec328c3d3d")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
@@ -138,6 +138,10 @@ function projectExistingRecoveryOptionalFields(existingRecovery) {
         "recovery_mode",
         "missing_required_fields",
         "suggested_flags",
+        "allowed_values",
+        "candidate_commands",
+        "candidate_commands_total",
+        "candidate_commands_truncated",
         "fallback_candidates",
         "next_best_command",
     ];
@@ -2307,13 +2311,14 @@ export async function runPmCli(rawArgv = process.argv.slice(2)) {
     runtimeExtensionDiscoverySnapshotCache = null;
     activeRuntimeExtensionCommandDescriptors = new Map();
     resetActiveExtensionRuntimeState();
-    const bootstrapInvocation = normalizeBootstrapInvocation(rawArgv);
-    const invocationArgv = bootstrapInvocation.argv;
-    const invocationProcessArgv = [process.argv[0], process.argv[1], ...invocationArgv];
-    const isBareInvocation = invocationArgv.length === 0;
+    let invocationArgv = [...rawArgv];
     let restorePmAuthor;
     let restorePagerPolicy;
     try {
+        const bootstrapInvocation = normalizeBootstrapInvocation(rawArgv);
+        invocationArgv = bootstrapInvocation.argv;
+        const invocationProcessArgv = [process.argv[0], process.argv[1], ...invocationArgv];
+        const isBareInvocation = invocationArgv.length === 0;
         const bootstrapGlobal = parseBootstrapGlobalOptions(invocationArgv);
         if (bootstrapGlobal.authorMissingValue) {
             throw new PmCliError("--author requires a non-empty value.", EXIT_CODE.USAGE, {
@@ -2454,4 +2459,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=52c705ab-a5c4-5b94-b806-4eaac31b6e9c
+//# debugId=80e9dea8-2bb3-50e7-b21e-50ec328c3d3d

package/dist/cli/register-assurance.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @module cli/register-assurance
+ *
+ * Thin Commander adapter over the transport-neutral public assurance action.
+ */
+import type { Command } from "commander";
+/** Register the declarative assurance command family. */
+export declare function registerAssuranceCommand(program: Command): void;

package/dist/cli/register-assurance.js

@@ -0,0 +1,52 @@
+
+!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]="1adbac08-0950-55be-82bf-cc4dc7b6ad18")}catch(e){}}();
+import { ASSURANCE_ACTIONS, ASSURANCE_DECLARATION_KINDS, runAssuranceAction, } from "../sdk/governance/assurance-action.js";
+import { printResult } from "../sdk/runtime-primitives.js";
+import { getGlobalOptions, readOptionString } from "./registration-helpers.js";
+async function runAssuranceCliAction(action, kindOrGate, id, options, command) {
+    const global = getGlobalOptions(command);
+    const isRun = action === "run";
+    const isVerdicts = action === "verdicts";
+    const result = await runAssuranceAction({
+        action,
+        ...(isRun || isVerdicts ? {} : { kind: kindOrGate }),
+        id: isRun || isVerdicts ? (id ?? kindOrGate) : id,
+        definition: readOptionString(options, "definition"),
+        trigger: readOptionString(options, "trigger"),
+        tree: readOptionString(options, "tree"),
+        gate: readOptionString(options, "gate"),
+        limit: readOptionString(options, "limit"),
+        dry_run: options.dryRun === true,
+        fullChangedFields: global.fullChangedFields,
+        idOnly: global.idOnly,
+        author: readOptionString(options, "author"),
+        message: readOptionString(options, "message"),
+    }, global);
+    printResult(result, global);
+    if (typeof result === "object" &&
+        result !== null &&
+        "exit_code" in result &&
+        result.exit_code === 1) {
+        process.exitCode = 1;
+    }
+}
+/** Register the declarative assurance command family. */
+export function registerAssuranceCommand(program) {
+    program
+        .command("assurance")
+        .argument("<action>", `Action: ${ASSURANCE_ACTIONS.join(", ")}`)
+        .argument("[kind]", `Declaration kind: ${ASSURANCE_DECLARATION_KINDS.join(", ")}; for run this may be the gate id`)
+        .argument("[id]", "Declaration or gate id")
+        .description("Declare and evaluate SDK-owned project assurance contracts.")
+        .option("--definition <json>", "JSON declaration for put")
+        .option("--trigger <value>", "Gate lifecycle trigger")
+        .option("--tree <value>", "Commit, tree, or snapshot identity being judged")
+        .option("--gate <id>", "Filter verdict history by gate id")
+        .option("--limit <number>", "Maximum newest verdicts returned")
+        .option("--dry-run", "Evaluate a gate without appending a verdict")
+        .option("--author <value>", "Mutation author override")
+        .option("--message <value>", "Audited mutation rationale")
+        .action(runAssuranceCliAction);
+}
+//# sourceMappingURL=register-assurance.js.map
+//# debugId=1adbac08-0950-55be-82bf-cc4dc7b6ad18

package/dist/cli/register-files-lookup.js

@@ -1,6 +1,7 @@
 
-!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]="dabf24f7-406d-57e0-af3c-25391325a1b4")}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]="452f6689-f5bd-5398-915b-52ce7e2fd55e")}catch(e){}}();
 import { runFilesLookup } from "../sdk/files.js";
+import { parseSourceLineRange } from "../sdk/traceability/source-traceability.js";
 import { EXIT_CODE, PmCliError } from "../sdk/runtime-primitives.js";
 import { getGlobalOptions, printResult } from "./registration-helpers.js";
 function parseIntegerBound(flag, minimum) {
@@ -26,6 +27,13 @@ async function runFilesLookupAction(paths, options, command) {
         offset: typeof options.offset === "number" ? options.offset : undefined,
         noTruncate: options.noTruncate === true,
         strictRead: options.strictRead === true,
+        explain: options.explain === true,
+        lineRange: typeof options.lines === "string"
+            ? parseSourceLineRange(options.lines)
+            : undefined,
+        decisionDepth: typeof options.decisionDepth === "number"
+            ? options.decisionDepth
+            : undefined,
     }, globalOptions);
     printResult(result, globalOptions);
 }
@@ -39,8 +47,11 @@ export function registerFilesLookupCommand(filesCommand) {
         .option("--offset <n>", "Number of referencing items to skip", parseIntegerBound("--offset", 0))
         .option("--no-truncate", "Return every referencing item")
         .option("--strict-read", "Fail when any authoritative item cannot be read")
-        .description("Find pm items that link the requested source paths.")
+        .option("--explain", "Include ranked source-to-work rationale")
+        .option("--lines <start:end>", "Attribute an inclusive source line range")
+        .option("--decision-depth <n>", "Maximum governing-decision relationship depth", parseIntegerBound("--decision-depth", 1))
+        .description("Find and explain pm items that govern requested source paths.")
         .action(runFilesLookupAction);
 }
 //# sourceMappingURL=register-files-lookup.js.map
-//# debugId=dabf24f7-406d-57e0-af3c-25391325a1b4
+//# debugId=452f6689-f5bd-5398-915b-52ce7e2fd55e