@unbrained/pm-cli 2026.8.10 → 2026.8.11

package/dist/cli/commander-usage.js

@@ -1,12 +1,12 @@
 
-!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]="a327ea76-ca7d-5f8f-aa2d-2f6f43052913")}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";
@@ -54,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) {
@@ -335,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) {
@@ -571,6 +596,35 @@ function resolveSuggestedRetryForMissingOption(message, invocationArgv) {
         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 = {}) {
     const rawMessage = typeof error === "object" && error !== null
@@ -585,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,
@@ -595,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,
     };
@@ -605,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,
@@ -614,6 +676,11 @@ export async function formatCommanderUsageMessage(error, rootProgram, extensionD
         providedOptionFlags,
         unknownOptionSuggestions,
         unknownOptionOtherCommands,
+        unknownOptionOtherCommandsTotal,
+        unknownOptionOtherCommandsTruncated,
+        unknownSubcommandPath,
+        unknownSubcommandToken,
+        unknownSubcommandAllowedValues,
         suggestedRetryCommand,
         failedExtensions,
     });
@@ -638,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,
     });
@@ -652,4 +724,4 @@ export const _testOnly = {
     suggestNearestLongFlags,
 };
 //# sourceMappingURL=commander-usage.js.map
-//# debugId=a327ea76-ca7d-5f8f-aa2d-2f6f43052913
+//# 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/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]="555e37d0-385a-5748-b0a5-760f48c94e90")}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",
     ];
@@ -2455,4 +2459,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=555e37d0-385a-5748-b0a5-760f48c94e90
+//# 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

package/dist/cli/register-mutation.js

@@ -1,6 +1,6 @@
 
-!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]="e5b9b4c9-c2eb-5282-99da-702a8887c4e4")}catch(e){}}();
-import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, } from "../sdk/runtime-primitives.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6c7d647c-e489-51e3-b84b-5b62b4114033")}catch(e){}}();
+import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES } from "../types/index.js";
 import { MERGE_DRIVER_ARTIFACT_VALUES, runMergeDriver, runMergeInstall, runMergeReconcile, runMergeReceiptReport, } from "./commands/merge.js";
@@ -675,7 +675,7 @@ function normalizePlanAliases(options) {
     normalized.blockedBy = planOptions.blockedBy;
     return normalized;
 }
-function assertKnownPlanSubcommand(subcommand, normalized, allowed) {
+function assertKnownPlanSubcommand(normalized, allowed) {
     if (!normalized) {
         throw new PmCliError(`pm plan requires a subcommand. Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, {
             code: "missing_required_argument",
@@ -692,7 +692,15 @@ function assertKnownPlanSubcommand(subcommand, normalized, allowed) {
     const examples = normalized === "list" || normalized === "ls"
         ? ["pm list --type Plan", "pm list-all --type Plan"]
         : undefined;
-    throw new PmCliError(`Unknown pm plan subcommand "${subcommand}". Allowed: ${allowed.join(", ")}`, EXIT_CODE.USAGE, examples ? { code: "unknown_subcommand", examples } : undefined);
+    throw createUnknownSubcommandError({
+        command_path: "plan",
+        token: normalized,
+        allowed,
+        examples,
+        retry_command: normalized === "list" || normalized === "ls"
+            ? "pm list --type Plan"
+            : undefined,
+    });
 }
 function parsePlanReorderTo(normalizedSubcommand, reorderToken) {
     if (normalizedSubcommand !== "reorder-step" ||
@@ -709,7 +717,7 @@ async function runPlanAction(subcommand, id, stepRef, reorderToken, options, com
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
     const normalizedSubcommand = (subcommand ?? "").trim().toLowerCase();
-    assertKnownPlanSubcommand(subcommand, normalizedSubcommand, PLAN_SUBCOMMANDS);
+    assertKnownPlanSubcommand(normalizedSubcommand, PLAN_SUBCOMMANDS);
     const planOptions = normalizePlanAliases(options);
     const reorderTo = parsePlanReorderTo(normalizedSubcommand, reorderToken);
     const planId = normalizedSubcommand === "create" &&
@@ -812,7 +820,12 @@ async function runMergeAction(subcommand, artifact, base, ours, theirs, options,
             await runMergeDriverSubcommand(artifact, base, ours, theirs, options, globalOptions);
             break;
         default:
-            throw new PmCliError(`Unknown merge subcommand "${subcommand}". Supported subcommands: install, reconcile, report, driver.`, EXIT_CODE.USAGE);
+            throw createUnknownSubcommandError({
+                command_path: "merge",
+                token: subcommand,
+                allowed: ["install", "reconcile", "report", "driver"],
+                display_name: "merge",
+            });
     }
     if (globalOptions.profile) {
         printError(`profile:command=merge took_ms=${Date.now() - startedAt}`);
@@ -890,7 +903,11 @@ async function runSchemaAction(subcommand, name, options, command) {
         normalizedSubcommand = "add-type";
     }
     if (!SCHEMA_SUBCOMMANDS.includes(normalizedSubcommand)) {
-        throw new PmCliError(`Unknown pm schema subcommand "${subcommand}". Allowed: ${SCHEMA_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "schema",
+            token: normalizedSubcommand,
+            allowed: SCHEMA_SUBCOMMANDS,
+        });
     }
     const result = await dispatchSchemaSubcommand(schemaModule, {
         normalizedSubcommand,
@@ -1070,7 +1087,11 @@ async function runProfileAction(subcommand, name, options, command) {
         });
     }
     if (!PROFILE_SUBCOMMANDS.includes(normalizedSubcommand)) {
-        throw new PmCliError(`Unknown pm profile subcommand "${subcommand}". Allowed: ${PROFILE_SUBCOMMANDS.join(", ")}`, EXIT_CODE.USAGE, { code: "unknown_subcommand" });
+        throw createUnknownSubcommandError({
+            command_path: "profile",
+            token: normalizedSubcommand,
+            allowed: PROFILE_SUBCOMMANDS,
+        });
     }
     const result = await dispatchProfileSubcommand(profileModule, normalizedSubcommand, name, options, globalOptions);
     // Profile inspection and schema staging do not mutate item content, so search caches stay valid (mirrors pm schema).
@@ -1817,4 +1838,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=e5b9b4c9-c2eb-5282-99da-702a8887c4e4
+//# debugId=6c7d647c-e489-51e3-b84b-5b62b4114033

package/dist/cli/register-operations.js

@@ -1,6 +1,6 @@
 
-!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]="4856ec1e-7841-5ad0-95e3-6e3057ed999c")}catch(e){}}();
-import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8bd1cf90-5ac8-5470-903d-b9b61d62bb85")}catch(e){}}();
+import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
 import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "../sdk/workspace-snapshot.js";
@@ -19,6 +19,7 @@ import { runStartBackgroundRun, runTestRunsWorker, } from "./commands/test-runs.
 import { runUpdate } from "./commands/update.js";
 import { runValidate } from "./commands/validate.js";
 import { buildBackgroundTestAllCommandArgs, applyActiveCommandResultService, buildBackgroundTestCommandArgs, addHiddenOption, collect, getGlobalOptions, invalidateSearchCachesForMutation, printError, printResult, readOptionString, } from "./registration-helpers.js";
+import { registerAssuranceCommand } from "./register-assurance.js";
 function resolveTelemetrySubcommand(namespaceOrSubcommand, subcommand) {
     const normalizedNamespace = namespaceOrSubcommand?.trim().toLowerCase();
     const normalizedSubcommand = subcommand?.trim().toLowerCase();
@@ -31,13 +32,13 @@ function resolveTelemetrySubcommand(namespaceOrSubcommand, subcommand) {
             : "status";
     }
     if (normalizedSubcommand !== undefined && normalizedSubcommand.length > 0) {
-        throw new PmCliError(`Unknown pm telemetry path "${namespaceOrSubcommand} ${subcommand}". Use "pm telemetry ${namespaceOrSubcommand}" or legacy alias "pm telemetry local-analytics ${normalizedSubcommand}".`, EXIT_CODE.USAGE, {
-            code: "unknown_subcommand",
+        throw createUnknownSubcommandError({
+            command_path: "telemetry",
+            token: `${namespaceOrSubcommand} ${subcommand}`,
+            allowed: ["status", "flush", "stats", "clear", "local-analytics"],
+            token_kind: "path",
             examples: [
-                "pm telemetry status",
-                "pm telemetry flush",
                 "pm telemetry stats --limit 10",
-                "pm telemetry clear",
                 "pm telemetry local-analytics status --json",
             ],
         });
@@ -372,11 +373,14 @@ async function runWorkspaceSnapshotAction(action, target, options, command) {
     const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
     const normalizedAction = action.trim().toLowerCase();
     if (!["create", "list", "inspect", "restore", "delete"].includes(normalizedAction)) {
-        throw new PmCliError(`Unknown workspace snapshot action "${action}". Use create, list, inspect, restore, or delete.`, EXIT_CODE.USAGE, {
-            code: "unknown_subcommand",
+        throw createUnknownSubcommandError({
+            command_path: "workspace snapshot",
+            token: action,
+            allowed: ["create", "list", "inspect", "restore", "delete"],
+            display_name: "workspace snapshot",
+            token_kind: "action",
             examples: [
                 "pm workspace snapshot create before-migration",
-                "pm workspace snapshot list",
                 "pm workspace snapshot restore before-migration",
             ],
         });
@@ -555,6 +559,7 @@ function addLinkedTestExecutionOptions(command) {
 }
 /** Implements register operation commands for the public runtime surface of this module. */
 export function registerOperationCommands(program) {
+    registerAssuranceCommand(program);
     const testCommand = program
         .command("test")
         .argument("<id>", "Item id")
@@ -858,4 +863,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=4856ec1e-7841-5ad0-95e3-6e3057ed999c
+//# debugId=8bd1cf90-5ac8-5470-903d-b9b61d62bb85