@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/dist/sdk/agent/refusal-reachability.js

@@ -1,6 +1,13 @@
-/** Recovery-reference kinds emitted by structured refusal envelopes. */
+/**
+ * @module sdk/agent/refusal-reachability
+ *
+ * Verifies real-entrypoint observations against refusal states declared by the
+ * generated public error-code catalog.
+ */
 
-!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]="e96813c2-e30f-5000-9935-281c564c19aa")}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]="7b488d32-9f92-5a80-965e-e2555cd49315")}catch(e){}}();
+import * as nodeModule from "node:module";
+/** Recovery-reference kinds emitted by structured refusal envelopes. */
 export const PM_RECOVERY_REFERENCE_KINDS = [
     "suggested_retry",
     "candidate_command",
@@ -11,12 +18,20 @@ export const PM_RECOVERY_REFERENCE_KINDS = [
 ];
 const RECOVERY_REFERENCE_FIELD_CONTRACTS = {
     suggested_retry: { kind: "suggested_retry", semantics: "recovery" },
+    retry_command: { kind: "suggested_retry", semantics: "recovery" },
     candidate_command: { kind: "candidate_command", semantics: "recovery" },
     candidate_commands: { kind: "candidate_command", semantics: "recovery" },
+    fallback_candidates: {
+        kind: "candidate_command",
+        semantics: "recovery",
+        nested_value_field: "command",
+    },
+    next_best_command: { kind: "candidate_command", semantics: "recovery" },
     example: { kind: "example", semantics: "recovery" },
     examples: { kind: "example", semantics: "recovery" },
     next_step: { kind: "next_step", semantics: "recovery" },
     next_steps: { kind: "next_step", semantics: "recovery" },
+    suggested_next_steps: { kind: "next_step", semantics: "recovery" },
     migration_hint: { kind: "migration_hint", semantics: "replacement" },
     migration_hints: { kind: "migration_hint", semantics: "replacement" },
     restore_with: {
@@ -24,6 +39,322 @@ const RECOVERY_REFERENCE_FIELD_CONTRACTS = {
         semantics: "behavior_preserving",
     },
 };
+/** Literal envelope fields recognized as recovery-reference producers. */
+export const PM_RECOVERY_REFERENCE_FIELDS = Object.freeze(Object.keys(RECOVERY_REFERENCE_FIELD_CONTRACTS));
+/** Resolve an own recovery-field contract without trusting object prototypes. */
+function recoveryReferenceContract(field) {
+    if (!Object.hasOwn(RECOVERY_REFERENCE_FIELD_CONTRACTS, field))
+        return undefined;
+    return RECOVERY_REFERENCE_FIELD_CONTRACTS[field];
+}
+const SOURCE_REGEXP_PREFIX_PUNCTUATORS = new Set([
+    ..."=([{,:;!?&|+-*%^~<>",
+    "=>",
+]);
+function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function skipQuotedSourceToken(source, index) {
+    const quote = source[index];
+    let next = index + 1;
+    let value = "";
+    while (next < source.length && source[next] !== quote) {
+        if (source[next] === "\\")
+            next += 2;
+        else {
+            value += source[next];
+            next += 1;
+        }
+    }
+    if (source[next] === quote)
+        next += 1;
+    return { next, value };
+}
+function canStartRegularExpression(previous) {
+    return (previous === undefined ||
+        (previous.kind === "punctuator" &&
+            SOURCE_REGEXP_PREFIX_PUNCTUATORS.has(previous.value)) ||
+        (previous.kind === "identifier" &&
+            ["return", "case", "throw", "else", "yield"].includes(previous.value)));
+}
+function sourceTriviaEnd(source, index) {
+    if (/\s/u.test(source[index]))
+        return index + 1;
+    if (source.startsWith("//", index)) {
+        const newline = source.indexOf("\n", index + 2);
+        return newline === -1 ? source.length : newline + 1;
+    }
+    if (!source.startsWith("/*", index))
+        return undefined;
+    // stripTypeScriptTypes validates block-comment termination before tokenization.
+    return source.indexOf("*/", index + 2) + 2;
+}
+function regularExpressionEnd(source, index, previous) {
+    if (source[index] !== "/" || !canStartRegularExpression(previous))
+        return undefined;
+    let next = index + 1;
+    let inClass = false;
+    while (next < source.length) {
+        if (source[next] === "\\")
+            next += 2;
+        else if (source[next] === "[") {
+            inClass = true;
+            next += 1;
+        }
+        else if (source[next] === "]") {
+            inClass = false;
+            next += 1;
+        }
+        else if (source[next] === "/" && !inClass) {
+            next += 1;
+            while (/[A-Za-z]/u.test(source.charAt(next)))
+                next += 1;
+            return next;
+        }
+        else
+            next += 1;
+    }
+    return next;
+}
+function readSourceSyntaxToken(source, index) {
+    const character = source[index];
+    if (character === "'" || character === '"' || character === "`") {
+        const quoted = skipQuotedSourceToken(source, index);
+        return character === "`"
+            ? { next: quoted.next }
+            : {
+                next: quoted.next,
+                token: { kind: "string", value: quoted.value, offset: index + 1 },
+            };
+    }
+    if (/[A-Za-z_$]/u.test(character)) {
+        let next = index + 1;
+        while (/[A-Za-z0-9_$]/u.test(source[next] ?? ""))
+            next += 1;
+        return {
+            next,
+            token: {
+                kind: "identifier",
+                value: source.slice(index, next),
+                offset: index,
+            },
+        };
+    }
+    const punctuator = source.startsWith("=>", index) ? "=>" : character;
+    return {
+        next: index + punctuator.length,
+        token: { kind: "punctuator", value: punctuator, offset: index },
+    };
+}
+/** Tokenize executable JavaScript while ignoring comments, templates, and regex bodies. */
+function tokenizeExecutableSource(source) {
+    const tokens = [];
+    let index = 0;
+    while (index < source.length) {
+        const ignoredEnd = sourceTriviaEnd(source, index);
+        if (ignoredEnd !== undefined) {
+            index = ignoredEnd;
+            continue;
+        }
+        const regexEnd = regularExpressionEnd(source, index, tokens.at(-1));
+        if (regexEnd !== undefined) {
+            index = regexEnd;
+            continue;
+        }
+        const read = readSourceSyntaxToken(source, index);
+        if (read.token)
+            tokens.push(read.token);
+        index = read.next;
+    }
+    return tokens;
+}
+const SOURCE_BRACE_FRAME_KINDS = new Set([
+    "object",
+    "block",
+    "pattern",
+]);
+const SOURCE_PATTERN_DECLARATIONS = new Set(["const", "let", "var"]);
+const SOURCE_CLOSING_TOKENS = new Set(["}", ")", "]"]);
+const SOURCE_OBJECT_PRECEDERS = new Set([
+    "=",
+    "(",
+    "[",
+    ",",
+    ":",
+    "?",
+    "return",
+]);
+function objectFrameKind(tokens, index, stack) {
+    const enclosingBrace = [...stack]
+        .reverse()
+        .find((frame) => SOURCE_BRACE_FRAME_KINDS.has(frame.kind));
+    if (enclosingBrace?.kind === "pattern")
+        return "pattern";
+    if (stack.at(-1)?.kind === "paren" && stack.at(-1)?.parameter_list)
+        return "pattern";
+    const previous = tokens[index - 1];
+    if (previous?.kind === "identifier" &&
+        SOURCE_PATTERN_DECLARATIONS.has(previous.value)) {
+        return "pattern";
+    }
+    if (previous?.value === "=>" || previous?.value === ")")
+        return "block";
+    return previous && SOURCE_OBJECT_PRECEDERS.has(previous.value)
+        ? "object"
+        : "block";
+}
+function openingSourceFrame(tokens, index, stack) {
+    const token = tokens[index];
+    if (token.value === "{") {
+        const kind = objectFrameKind(tokens, index, stack);
+        return {
+            kind,
+            ...(kind === "object" ? { member_start: true, candidates: [] } : {}),
+        };
+    }
+    if (token.value === "[")
+        return { kind: "array" };
+    if (token.value !== "(")
+        return undefined;
+    const previous = tokens[index - 1];
+    const beforePrevious = tokens[index - 2];
+    const parameterList = previous?.value === "function" || beforePrevious?.value === "function";
+    return { kind: "paren", ...(parameterList ? { parameter_list: true } : {}) };
+}
+function staticObjectMember(frame, token, next) {
+    if (frame?.kind !== "object" ||
+        !frame.member_start ||
+        (token.kind !== "identifier" && token.kind !== "string") ||
+        next?.value !== ":" ||
+        !/^[A-Za-z][A-Za-z0-9_]*$/u.test(token.value)) {
+        return undefined;
+    }
+    return { field: token.value, offset: token.offset };
+}
+function isPatternLikeObjectClosure(tokens, index) {
+    return ((tokens[index + 1]?.value === ")" && tokens[index + 2]?.value === "=>") ||
+        tokens[index + 1]?.value === "=");
+}
+/** Parse static object-literal members without treating patterns or labels as producers. */
+function scanSourcePropertyTokens(source) {
+    const tokens = tokenizeExecutableSource(nodeModule.stripTypeScriptTypes(source, { mode: "strip" }));
+    const properties = [];
+    const stack = [];
+    for (const [index, token] of tokens.entries()) {
+        const frame = stack.at(-1);
+        const property = staticObjectMember(frame, token, tokens[index + 1]);
+        if (property)
+            frame.candidates.push(property);
+        const opening = openingSourceFrame(tokens, index, stack);
+        if (opening) {
+            stack.push(opening);
+        }
+        else if (SOURCE_CLOSING_TOKENS.has(token.value)) {
+            const closed = stack.pop();
+            if (closed?.kind === "object" &&
+                !isPatternLikeObjectClosure(tokens, index)) {
+                properties.push(...closed.candidates);
+            }
+        }
+        else if (token.value === "," && frame?.kind === "object") {
+            frame.member_start = true;
+        }
+        else if (frame?.kind === "object" && token.value !== ":") {
+            frame.member_start = false;
+        }
+    }
+    return properties;
+}
+function sourceLineStarts(source) {
+    const starts = [0];
+    for (let index = 0; index < source.length; index += 1) {
+        if (source[index] === "\n")
+            starts.push(index + 1);
+    }
+    return starts;
+}
+function sourceLineAtOffset(starts, offset) {
+    let low = 0;
+    let high = starts.length;
+    while (low < high) {
+        const middle = Math.floor((low + high) / 2);
+        if (starts[middle] <= offset)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return low;
+}
+/** Census syntax-parsed structured-envelope producers without executing source code. */
+export function censusPmRecoveryReferenceProducers(sources) {
+    const producers = [];
+    const findings = [];
+    for (const source of [...sources].sort((left, right) => compareCodeUnits(left.path, right.path))) {
+        const lineStarts = sourceLineStarts(source.content);
+        let properties;
+        try {
+            properties = scanSourcePropertyTokens(source.content);
+        }
+        catch (error) {
+            findings.push({
+                kind: "invalid_source",
+                subject: source.path,
+                detail: `${source.path} could not be parsed for recovery producers: ${String(error)}.`,
+            });
+            continue;
+        }
+        for (const property of properties) {
+            const field = property.field;
+            const line = sourceLineAtOffset(lineStarts, property.offset);
+            const contract = recoveryReferenceContract(field);
+            if (contract) {
+                producers.push({
+                    path: source.path,
+                    line,
+                    field: field,
+                    kind: contract.kind,
+                });
+            }
+            else if (/(?:retry_command|candidate_command|fallback_candidate|next_best_command|example|next_step|migration_hint|restore_with)/u.test(field) &&
+                !/(?:_total|_truncated)$/u.test(field)) {
+                findings.push({
+                    kind: "unknown_recovery_field",
+                    subject: `${source.path}:${line}:${field}`,
+                    detail: `${field} resembles a recovery reference but has no typed field contract.`,
+                });
+            }
+        }
+    }
+    const producerCountByKind = Object.fromEntries(PM_RECOVERY_REFERENCE_KINDS.map((kind) => [
+        kind,
+        producers.filter((producer) => producer.kind === kind).length,
+    ]));
+    for (const kind of PM_RECOVERY_REFERENCE_KINDS) {
+        if (producerCountByKind[kind] === 0) {
+            findings.push({
+                kind: "missing_kind_producer",
+                subject: kind,
+                detail: `No source producer emits the ${kind} recovery-reference kind.`,
+            });
+        }
+    }
+    producers.sort((left, right) => left.path !== right.path
+        ? compareCodeUnits(left.path, right.path)
+        : left.line !== right.line
+            ? left.line - right.line
+            : compareCodeUnits(left.field, right.field));
+    findings.sort((left, right) => left.subject !== right.subject
+        ? compareCodeUnits(left.subject, right.subject)
+        : compareCodeUnits(left.kind, right.kind));
+    return {
+        ok: findings.length === 0,
+        scanned_file_count: sources.length,
+        producer_count: producers.length,
+        producer_count_by_kind: producerCountByKind,
+        producers,
+        findings,
+    };
+}
 /** Derive typed obligations from every recognized recovery field in an emitted envelope. */
 export function derivePmRecoveryReferenceObligations(probeId, envelope) {
     const obligations = [];
@@ -34,16 +365,27 @@ export function derivePmRecoveryReferenceObligations(probeId, envelope) {
         }
         if (typeof value !== "object" || value === null)
             return;
-        for (const [key, entry] of Object.entries(value).sort(([left], [right]) => left.localeCompare(right))) {
-            const baseContract = RECOVERY_REFERENCE_FIELD_CONTRACTS[key];
+        for (const [key, entry] of Object.entries(value).sort(([left], [right]) => compareCodeUnits(left, right))) {
+            const baseContract = recoveryReferenceContract(key);
             const contract = baseContract?.kind === "migration_hint" &&
                 value.semantics === "behavior_preserving"
                 ? { ...baseContract, semantics: "behavior_preserving" }
                 : baseContract;
-            const entries = Array.isArray(entry) ? entry : [entry];
+            const entries = [entry].flat();
             if (contract !== undefined) {
                 entries.forEach((candidate, index) => {
-                    if (typeof candidate !== "string" || candidate.trim().length === 0)
+                    const nestedValueField = "nested_value_field" in contract &&
+                        typeof contract.nested_value_field === "string"
+                        ? contract.nested_value_field
+                        : undefined;
+                    const resolvedCandidate = nestedValueField &&
+                        typeof candidate === "object" &&
+                        candidate !== null &&
+                        !Array.isArray(candidate)
+                        ? candidate[nestedValueField]
+                        : candidate;
+                    if (typeof resolvedCandidate !== "string" ||
+                        resolvedCandidate.trim().length === 0)
                         return;
                     const coordinate = [...path, key, String(index)]
                         .map((segment) => encodeURIComponent(segment))
@@ -53,7 +395,7 @@ export function derivePmRecoveryReferenceObligations(probeId, envelope) {
                         probe_id: probeId,
                         kind: contract.kind,
                         semantics: contract.semantics,
-                        value: candidate,
+                        value: resolvedCandidate,
                     });
                 });
             }
@@ -225,4 +567,4 @@ export function verifyPmRecoveryReferences(obligations, observations) {
     };
 }
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=e96813c2-e30f-5000-9935-281c564c19aa
+//# debugId=7b488d32-9f92-5a80-965e-e2555cd49315

package/dist/sdk/authoring.d.ts

@@ -15,4 +15,4 @@ export { planProfileApplication, type ProfileApplicationPlan, type ProfileChange
 export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, type CollectUsedExtensionCapabilitiesOptions, type ExtensionCapabilityUsageReconciliation, } from "../core/extensions/capability-usage.js";
 export { renderExtensionSurfaceMarkdown, type ExtensionSurfaceMarkdownOptions, } from "../core/extensions/activation-summary-markdown.js";
 export { createExtensionContributionInventory, normalizeExtensionContributionInventory, } from "../core/extensions/contribution-inventory.js";
-export type { AfterCommandAffectedItem, AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, BeforeMutationHook, BeforeMutationHookContext, BeforeMutationHookDecision, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandHandlerResult, ExtensionCommandSdk, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDeactivationFailure, ExtensionDeactivationOptions, ExtensionDeactivationResult, ExtensionDiagnostic, ExtensionContributionInventory, ExtensionDiscoveryResult, ExtensionHookRegistry, ExtensionSelfIdentity, ExtensionLoadResult, ExtensionManifest, ExtensionManifestEngines, ExtensionMutationGuardSdk, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, ImportExportRegistrationOptions, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RegisteredExtensionExporter, RegisteredExtensionFlagDefinitions, RegisteredExtensionHook, RegisteredExtensionImporter, RegisteredExtensionProjectProfile, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, ServiceOverrideDecision, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";
+export type { AfterCommandAffectedItem, AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, BeforeMutationHook, BeforeMutationHookContext, BeforeMutationHookDecision, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandHandlerResult, ExtensionCommandSdk, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExporterArtifactOutputContract, ExporterRegistrationOptions, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDeactivationFailure, ExtensionDeactivationOptions, ExtensionDeactivationResult, ExtensionDiagnostic, ExtensionContributionInventory, ExtensionDiscoveryResult, ExtensionHookRegistry, ExtensionSelfIdentity, ExtensionLoadResult, ExtensionManifest, ExtensionManifestEngines, ExtensionMutationGuardSdk, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, ImportExportRegistrationOptions, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RegisteredExtensionExporter, RegisteredExporterArtifactOutputContract, RegisteredExtensionFlagDefinitions, RegisteredExtensionHook, RegisteredExtensionImporter, RegisteredExtensionProjectProfile, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, ServiceOverrideDecision, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";

package/dist/sdk/authoring.js

@@ -4,7 +4,7 @@
  * Provides the focused extension and package authoring surface.
  */
 
-!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]="99a9b24a-4bc7-50da-8333-e76086f0e303")}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]="6260572c-1496-58ef-9377-0825f4183bc6")}catch(e){}}();
 export * from "./compose.js";
 export * from "./define.js";
 export * from "./extension-contracts.js";
@@ -18,4 +18,4 @@ export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabil
 export { renderExtensionSurfaceMarkdown, } from "../core/extensions/activation-summary-markdown.js";
 export { createExtensionContributionInventory, normalizeExtensionContributionInventory, } from "../core/extensions/contribution-inventory.js";
 //# sourceMappingURL=authoring.js.map
-//# debugId=99a9b24a-4bc7-50da-8333-e76086f0e303
+//# debugId=6260572c-1496-58ef-9377-0825f4183bc6

package/dist/sdk/cli-bootstrap.d.ts

@@ -3,8 +3,8 @@
  *
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
-import { EXECUTABLE_COMMAND_ALIASES, type CliFlagContract } from "./cli-contracts.js";
-export { EXECUTABLE_COMMAND_ALIASES };
+import { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, type CliFlagContract, type PmCommandAliasContract, type PmCommandAliasLifecycle, type PmCommandAliasRegistration } from "./cli-contracts.js";
+export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, type PmCommandAliasContract, type PmCommandAliasLifecycle, type PmCommandAliasRegistration, };
 /** Documents the bootstrap global options payload exchanged by command, SDK, and package integrations. */
 export interface BootstrapGlobalOptions {
     /** Filesystem path used for path resolution. */

package/dist/sdk/cli-bootstrap.js

@@ -4,9 +4,9 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!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]="eccdb2d2-da6f-555b-ba1b-8339f9b64f1a")}catch(e){}}();
-import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
-export { EXECUTABLE_COMMAND_ALIASES };
+!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]="d45455ca-9496-5b8c-906c-d33d3d890e68")}catch(e){}}();
+import { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
+export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -895,4 +895,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=eccdb2d2-da6f-555b-ba1b-8339f9b64f1a
+//# debugId=d45455ca-9496-5b8c-906c-d33d3d890e68

package/dist/sdk/cli-contracts/command-aliases.d.ts

@@ -1,7 +1,39 @@
 /**
  * @module sdk/cli-contracts/command-aliases
  *
- * Defines executable command aliases shared by bootstrap parsing and SDK package scaffolding.
+ * Declares command aliases once so CLI registration, bootstrap parsing,
+ * contracts, completions, and package authors can share one compatibility
+ * policy instead of maintaining parallel spelling lists.
  */
-/** High-frequency executable aliases whose targets accept the same positional and flag contracts. */
+/** Lifecycle policy applied to a command alias. */
+export type PmCommandAliasLifecycle = "permanent" | "deprecated";
+/** Registration mechanism used to preserve an alias invocation. */
+export type PmCommandAliasRegistration = "bootstrap" | "commander";
+/** Machine-readable compatibility contract for one executable command alias. */
+export interface PmCommandAliasContract {
+    /** Legacy or ergonomic spelling accepted at the command root. */
+    alias: string;
+    /** Canonical command path agents should discover and generate. */
+    canonical: string;
+    /** Canonical tokens inserted before user-provided options and arguments. */
+    canonical_argv: readonly string[];
+    /** Whether the alias is permanent ergonomics or migration-only compatibility. */
+    lifecycle: PmCommandAliasLifecycle;
+    /** Whether default help and completion discovery omit the alias. */
+    hidden: boolean;
+    /** Runtime layer that keeps the alias executable. */
+    registration: PmCommandAliasRegistration;
+    /** PM item that owns the compatibility disposition. */
+    owner: string;
+}
+/**
+ * Public command-alias table. Deprecated aliases must remain executable but
+ * are intentionally absent from default help and completion discovery.
+ */
+export declare const PM_COMMAND_ALIAS_CONTRACTS: readonly PmCommandAliasContract[];
+/** High-frequency executable aliases whose targets accept identical arguments. */
 export declare const EXECUTABLE_COMMAND_ALIASES: Readonly<Record<string, string>>;
+/** Resolve one declared command alias without inferring from its spelling. */
+export declare function resolvePmCommandAlias(alias: string): PmCommandAliasContract | undefined;
+/** Render the stable one-line migration hint emitted for deprecated aliases. */
+export declare function renderPmCommandAliasMigrationHint(contract: PmCommandAliasContract): string;

package/dist/sdk/cli-contracts/command-aliases.js

@@ -1,19 +1,70 @@
 /**
  * @module sdk/cli-contracts/command-aliases
  *
- * Defines executable command aliases shared by bootstrap parsing and SDK package scaffolding.
+ * Declares command aliases once so CLI registration, bootstrap parsing,
+ * contracts, completions, and package authors can share one compatibility
+ * policy instead of maintaining parallel spelling lists.
+ */
+/**
+ * Public command-alias table. Deprecated aliases must remain executable but
+ * are intentionally absent from default help and completion discovery.
  */
-/** High-frequency executable aliases whose targets accept the same positional and flag contracts. */
 
-!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]="940f11a8-f40d-5169-ba74-e91920d32c4a")}catch(e){}}();
-export const EXECUTABLE_COMMAND_ALIASES = {
-    fetch: "get",
-    read: "get",
-    show: "get",
-    view: "get",
-    comment: "comments",
-    note: "notes",
-    learning: "learnings",
-};
+!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]="cde15ba9-270e-5e05-baba-7dafbe1bd5da")}catch(e){}}();
+export const PM_COMMAND_ALIAS_CONTRACTS = [
+    ...[
+        ["fetch", "get"],
+        ["read", "get"],
+        ["show", "get"],
+        ["view", "get"],
+        ["comment", "comments"],
+        ["note", "notes"],
+        ["learning", "learnings"],
+    ].map(([alias, canonical]) => ({
+        alias,
+        canonical,
+        canonical_argv: [canonical],
+        lifecycle: "permanent",
+        hidden: false,
+        registration: "bootstrap",
+        owner: "pm-pbyu",
+    })),
+    {
+        alias: "list-all",
+        canonical: "list",
+        canonical_argv: ["list", "--all"],
+        lifecycle: "deprecated",
+        hidden: true,
+        registration: "commander",
+        owner: "pm-pfqi",
+    },
+    ...[
+        ["list-draft", "draft"],
+        ["list-open", "open"],
+        ["list-in-progress", "in_progress"],
+        ["list-blocked", "blocked"],
+        ["list-closed", "closed"],
+        ["list-canceled", "canceled"],
+    ].map(([alias, status]) => ({
+        alias,
+        canonical: "list",
+        canonical_argv: ["list", "--status", status],
+        lifecycle: "deprecated",
+        hidden: true,
+        registration: "commander",
+        owner: "pm-pfqi",
+    })),
+];
+/** High-frequency executable aliases whose targets accept identical arguments. */
+export const EXECUTABLE_COMMAND_ALIASES = Object.fromEntries(PM_COMMAND_ALIAS_CONTRACTS.filter((contract) => contract.registration === "bootstrap").map((contract) => [contract.alias, contract.canonical]));
+/** Resolve one declared command alias without inferring from its spelling. */
+export function resolvePmCommandAlias(alias) {
+    const normalized = alias.trim().toLowerCase();
+    return PM_COMMAND_ALIAS_CONTRACTS.find((contract) => contract.alias === normalized);
+}
+/** Render the stable one-line migration hint emitted for deprecated aliases. */
+export function renderPmCommandAliasMigrationHint(contract) {
+    return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
+}
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=940f11a8-f40d-5169-ba74-e91920d32c4a
+//# debugId=cde15ba9-270e-5e05-baba-7dafbe1bd5da

package/dist/sdk/cli-contracts/enum-contracts.d.ts

@@ -46,6 +46,10 @@ export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction> | PmE
  * package verbs are flattened for transports that expose one action string.
  */
 export declare const PM_TOOL_ACTIONS: readonly PmToolAction[];
+/** Deprecated compatibility actions accepted by the SDK but omitted from canonical MCP discovery. */
+export declare const PM_DEPRECATED_TOOL_ACTIONS: readonly PmToolAction[];
+/** Canonical actions presented to MCP clients and unscoped contract consumers. */
+export declare const PM_DISCOVERABLE_TOOL_ACTIONS: readonly PmToolAction[];
 /** Static CLI-to-tool action parity evidence used by quality gates and tests. */
 export declare function analyzePmToolActionParity(cliCommands?: readonly string[], toolActions?: readonly string[], waivers?: Readonly<Record<string, string>>): {
     missing_cli_actions: string[];

package/dist/sdk/cli-contracts/enum-contracts.js

@@ -4,8 +4,9 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!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]="818ca284-2aaa-5d35-b280-8c963d443b0c")}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]="d05ce92b-bee8-5cce-afc2-8c7901306a30")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
+import { PM_COMMAND_ALIAS_CONTRACTS } from "./command-aliases.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
 export const PM_EXTENSION_CAPABILITY_CONTRACTS = [
     ...KNOWN_EXTENSION_CAPABILITIES,
@@ -160,6 +161,12 @@ export const PM_TOOL_ACTIONS = Object.freeze(PM_CORE_COMMAND_NAMES.flatMap((comm
     }
     return [command];
 }));
+/** Deprecated compatibility actions accepted by the SDK but omitted from canonical MCP discovery. */
+export const PM_DEPRECATED_TOOL_ACTIONS = Object.freeze(PM_COMMAND_ALIAS_CONTRACTS.filter((contract) => contract.lifecycle === "deprecated" &&
+    contract.registration === "commander" &&
+    PM_TOOL_ACTIONS.includes(contract.alias)).map((contract) => contract.alias));
+/** Canonical actions presented to MCP clients and unscoped contract consumers. */
+export const PM_DISCOVERABLE_TOOL_ACTIONS = Object.freeze(PM_TOOL_ACTIONS.filter((action) => !PM_DEPRECATED_TOOL_ACTIONS.includes(action)));
 /** Static CLI-to-tool action parity evidence used by quality gates and tests. */
 export function analyzePmToolActionParity(cliCommands = PM_CORE_COMMAND_NAMES, toolActions = PM_TOOL_ACTIONS, waivers = PM_CLI_ONLY_TOOL_ACTION_WAIVERS) {
     const toolActionSet = new Set(toolActions);
@@ -191,4 +198,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=818ca284-2aaa-5d35-b280-8c963d443b0c
+//# debugId=d05ce92b-bee8-5cce-afc2-8c7901306a30