@unbrained/pm-cli 2026.8.17 → 2026.8.19

package/dist/core/store/settings.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Settings.
  */
 
-!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]="a434b9ea-4692-51c5-8761-0f1759fff394")}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]="67bf189e-e816-536d-9051-589a2e468423")}catch(e){}}();
 import { validateSettings } from "./settings-validator.js";
 import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../extensions/index.js";
 import { GOVERNANCE_PRESET_DEFAULTS, SETTINGS_DEFAULTS, } from "../shared/constants.js";
@@ -710,6 +710,7 @@ function mergeSettings(settings) {
         },
         checkpoints: { ...defaults.checkpoints, ...settings.checkpoints },
         output: { ...defaults.output, ...settings.output },
+        ux: { ...defaults.ux, ...settings.ux },
         history: {
             ...defaults.history,
             ...settings.history,
@@ -777,6 +778,9 @@ function orderSerializedSettingsSections(ordered) {
     ordered.output = orderObject(ordered.output, [
         "default_format",
     ]);
+    ordered.ux = orderObject(ordered.ux, [
+        "deprecation_hints",
+    ]);
     ordered.history = orderObject(ordered.history, [
         "missing_stream",
         "compact_policy",
@@ -934,6 +938,7 @@ function buildSerializeBaseSettings(settings) {
         mutation_guard: valueOrDefault(settings.mutation_guard, SETTINGS_DEFAULTS.mutation_guard),
         checkpoints: valueOrDefault(settings.checkpoints, SETTINGS_DEFAULTS.checkpoints),
         output: valueOrDefault(settings.output, SETTINGS_DEFAULTS.output),
+        ux: valueOrDefault(settings.ux, SETTINGS_DEFAULTS.ux),
         history: valueOrDefault(settings.history, SETTINGS_DEFAULTS.history),
         validation: valueOrDefault(settings.validation, SETTINGS_DEFAULTS.validation),
         workflow: valueOrDefault(settings.workflow, SETTINGS_DEFAULTS.workflow),
@@ -1084,6 +1089,7 @@ const SETTINGS_TOP_LEVEL_KEY_ORDER = [
     "locks",
     "checkpoints",
     "output",
+    "ux",
     "history",
     "validation",
     "governance",
@@ -1298,4 +1304,4 @@ export const settingsStoreTestOnly = {
     selectedSettingsReadCacheSignaturesEqual,
 };
 //# sourceMappingURL=settings.js.map
-//# debugId=a434b9ea-4692-51c5-8761-0f1759fff394
+//# debugId=67bf189e-e816-536d-9051-589a2e468423

package/dist/mcp/tool-definitions.js

@@ -4,8 +4,8 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="d440a41a-ae54-55fd-b939-5404a1edcdd7")}catch(e){}}();
-import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.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]="90896fb6-ee3e-575d-b103-bbc1a83c6672")}catch(e){}}();
+import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
 const CANONICAL_OUTPUT_SESSION_TOOL_PROPERTY = buildPmActionToolInputSchema("list").properties.outputSession;
@@ -65,9 +65,9 @@ const idSchema = {
     description: "pm item id, for example pm-abc1.",
 };
 // pm-fd8n: derive the pm_run action enumeration from the canonical
-// PM_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
+// PM_DISCOVERABLE_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
 // MCP-facing description can never drift from the actual supported actions.
-const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_TOOL_ACTIONS.join(", ")}. ` +
+const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_DISCOVERABLE_TOOL_ACTIONS.join(", ")}. ` +
     "Package-owned actions are available dynamically when their provider package is installed.";
 const LIST_TOP_LEVEL_OPTION_PROPERTIES = {
     status: { type: "string", description: "Alias for options.status." },
@@ -111,7 +111,7 @@ const RAW_TOOLS = [
         inputSchema: objectSchema({
             action: {
                 type: "string",
-                enum: [...PM_TOOL_ACTIONS],
+                enum: [...PM_DISCOVERABLE_TOOL_ACTIONS],
                 description: PM_RUN_ACTION_DESCRIPTION,
             },
             id: idSchema,
@@ -209,7 +209,7 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_events",
-        description: "Read a bounded, cursor-resumable page of committed mutation events across item history streams.",
+        description: "Read a bounded, cursor-resumable page of committed mutation events across item history streams. Batch cursors are the token-efficient default; pass cursorMode=row for per-event checkpoints.",
         inputSchema: objectSchema({
             since: {
                 type: "string",
@@ -235,6 +235,11 @@ const RAW_TOOLS = [
             },
             limit: { type: "integer", minimum: 0, maximum: 1000 },
             full: { type: "boolean" },
+            cursorMode: {
+                type: "string",
+                enum: ["batch", "row"],
+                description: "Cursor framing: batch returns one terminal next_cursor (default); row also adds a cursor to every event.",
+            },
         }),
     },
     {
@@ -743,4 +748,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=d440a41a-ae54-55fd-b939-5404a1edcdd7
+//# debugId=90896fb6-ee3e-575d-b103-bbc1a83c6672

package/dist/sdk/agent/refusal-closure.d.ts

@@ -0,0 +1,41 @@
+/** One real refusal and the outcome of executing its advertised retry. */
+export interface PmRefusalClosureObservation {
+    /** Stable corpus identifier. */
+    probe_id: string;
+    /** Public entrypoint that refused the invocation. */
+    entrypoint: string;
+    /** Process exit code returned by the refusal. */
+    exit_code: number;
+    /** Rejected closed-domain token. */
+    rejected_value: string;
+    /** Complete accepted domain emitted by the refusal. */
+    allowed_values: readonly string[];
+    /** Exact command emitted for recovery. */
+    suggested_retry: string;
+    /** Whether executing the advertised retry succeeded. */
+    retry_succeeded: boolean;
+}
+/** One missing or contradictory recovery primitive. */
+export interface PmRefusalClosureFinding {
+    /** Stable finding code. */
+    code: "accepted_rejected_value" | "duplicate_probe" | "empty_corpus" | "missing_allowed_values" | "missing_suggested_retry" | "non_refusal_exit" | "retry_failed";
+    /** Stable corpus identifier. */
+    probe_id: string;
+    /** Actionable mismatch detail. */
+    detail: string;
+}
+/** Complete recovery-closure score and its fail-closed findings. */
+export interface PmRefusalClosureReport {
+    /** Whether every refusal was self-contained and executable. */
+    ok: boolean;
+    /** Number of unique probes scored. */
+    probe_count: number;
+    /** Number of probes with complete successful closure. */
+    closed_probe_count: number;
+    /** Closed probes divided by unique probes. */
+    closure_fraction: number;
+    /** Stable ordered findings. */
+    findings: readonly PmRefusalClosureFinding[];
+}
+/** Score structured closed-domain refusals and executable retries. */
+export declare function scorePmRefusalClosure(observations: readonly PmRefusalClosureObservation[]): PmRefusalClosureReport;

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

@@ -0,0 +1,92 @@
+/**
+ * @module sdk/agent/refusal-closure
+ *
+ * Scores whether a structured refusal contains enough executable context for
+ * an agent to recover without another discovery round trip.
+ */
+
+!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]="65cfaa41-6f53-5339-8b55-c1a4d3660c5d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+/** Return every closure defect contributed by one unique observation. */
+function listObservationFindings(observation) {
+    return [
+        observation.exit_code !== EXIT_CODE.USAGE
+            ? {
+                code: "non_refusal_exit",
+                probe_id: observation.probe_id,
+                detail: `${observation.entrypoint} returned exit code ${observation.exit_code}; a structured usage refusal must return ${EXIT_CODE.USAGE}.`,
+            }
+            : undefined,
+        observation.allowed_values.length === 0
+            ? {
+                code: "missing_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted its complete accepted value domain.",
+            }
+            : undefined,
+        observation.allowed_values.includes(observation.rejected_value)
+            ? {
+                code: "accepted_rejected_value",
+                probe_id: observation.probe_id,
+                detail: `${observation.rejected_value} is both rejected and advertised as allowed.`,
+            }
+            : undefined,
+        observation.suggested_retry.trim().length === 0
+            ? {
+                code: "missing_suggested_retry",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted an executable suggested retry.",
+            }
+            : undefined,
+        !observation.retry_succeeded
+            ? {
+                code: "retry_failed",
+                probe_id: observation.probe_id,
+                detail: "The advertised suggested retry did not succeed.",
+            }
+            : undefined,
+    ];
+}
+/** Score structured closed-domain refusals and executable retries. */
+export function scorePmRefusalClosure(observations) {
+    const findings = [];
+    const seen = new Set();
+    let closedProbeCount = 0;
+    if (observations.length === 0) {
+        findings.push({
+            code: "empty_corpus",
+            probe_id: "corpus",
+            detail: "At least one real refusal observation is required.",
+        });
+    }
+    for (const observation of observations) {
+        if (seen.has(observation.probe_id)) {
+            findings.push({
+                code: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        seen.add(observation.probe_id);
+        const findingCount = findings.length;
+        for (const finding of listObservationFindings(observation)) {
+            if (finding !== undefined)
+                findings.push(finding);
+        }
+        if (findings.length === findingCount)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: seen.size,
+        closed_probe_count: closedProbeCount,
+        closure_fraction: seen.size === 0 ? 0 : closedProbeCount / seen.size,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-closure.js.map
+//# debugId=65cfaa41-6f53-5339-8b55-c1a4d3660c5d

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -37,7 +37,7 @@ export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[numbe
 /** Behavioral promise attached to a recovery reference. */
 export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
 /** Literal envelope fields recognized as recovery-reference producers. */
-export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "candidate_command" | "example" | "next_step" | "retry_command")[];
+export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "example" | "candidate_command" | "next_step" | "retry_command")[];
 /** One source file supplied to the producer-census analyzer. */
 export interface PmRecoveryProducerSource {
     /** Repository-relative source path. */

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

@@ -5,8 +5,8 @@
  * 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]="70af2366-a675-5631-8edb-4ebeef4bb786")}catch(e){}}();
-import { stripTypeScriptTypes } from "node:module";
+!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",
@@ -237,7 +237,7 @@ function isPatternLikeObjectClosure(tokens, index) {
 }
 /** Parse static object-literal members without treating patterns or labels as producers. */
 function scanSourcePropertyTokens(source) {
-    const tokens = tokenizeExecutableSource(stripTypeScriptTypes(source, { mode: "strip" }));
+    const tokens = tokenizeExecutableSource(nodeModule.stripTypeScriptTypes(source, { mode: "strip" }));
     const properties = [];
     const stack = [];
     for (const [index, token] of tokens.entries()) {
@@ -567,4 +567,4 @@ export function verifyPmRecoveryReferences(obligations, observations) {
     };
 }
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=70af2366-a675-5631-8edb-4ebeef4bb786
+//# debugId=7b488d32-9f92-5a80-965e-e2555cd49315

package/dist/sdk/agent-capability-contracts.d.ts

@@ -1,5 +1,7 @@
 /** Visibility tiers shared by CLI help, completions, docs, extensions, and MCP. */
 export type PmCommandVisibilityTier = "core" | "standard" | "full" | "internal";
+/** Stable capability families shared by every agent-facing command surface. */
+export type PmCommandCapabilityFamily = "workspace" | "intake" | "context" | "lifecycle" | "evidence" | "graph" | "quality" | "automation" | "extensions" | "internal";
 /** One command's canonical agent-surface visibility declaration. */
 export interface PmCommandVisibilityContract {
     /** Canonical command path. */
@@ -7,6 +9,13 @@ export interface PmCommandVisibilityContract {
     /** Minimum surface tier that advertises the command. */
     tier: PmCommandVisibilityTier;
 }
+/** Complete command capability contract with visibility and family ownership. */
+export interface PmCommandCapabilityContract extends PmCommandVisibilityContract {
+    /** Exactly one stable capability family used to group the command. */
+    family: PmCommandCapabilityFamily;
+}
+/** Resolve one command's stable capability family. */
+export declare function resolvePmCommandCapabilityFamily(command: string): PmCommandCapabilityFamily;
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -14,11 +23,15 @@ export interface PmCommandVisibilityContract {
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
+export declare const PM_COMMAND_CAPABILITY_CONTRACTS: readonly PmCommandCapabilityContract[];
+/** Backward-compatible tier-only projection of the capability contract. */
 export declare const PM_COMMAND_VISIBILITY_CONTRACTS: readonly PmCommandVisibilityContract[];
 /** Resolve one command's declared tier; extension commands default to standard. */
 export declare function resolvePmCommandVisibilityTier(command: string, extensionTier?: PmCommandVisibilityTier): PmCommandVisibilityTier;
 /** Return commands visible at a requested tier, preserving contract order. */
 export declare function listPmCommandsForTier(tier: Exclude<PmCommandVisibilityTier, "internal">): string[];
+/** Return commands in one capability family, preserving contract order. */
+export declare function listPmCommandsForFamily(family: PmCommandCapabilityFamily): string[];
 /** MCP profile names accepted by the server and embedding hosts. */
 export type PmMcpToolProfile = "core" | "standard" | "full" | "custom";
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="6fc2cd04-2fe4-5a0e-944d-fab0f86509e2")}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]="dd74bc56-9971-59b9-8d2b-a6cc78b0a650")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -46,6 +46,92 @@ const STANDARD_COMMANDS = new Set([
     "schema",
     "test",
 ]);
+const COMMANDS_BY_FAMILY = Object.freeze({
+    workspace: new Set([
+        "config",
+        "gc",
+        "health",
+        "init",
+        "merge",
+        "profile",
+        "schema",
+        "telemetry",
+        "workspace",
+    ]),
+    intake: new Set(["copy", "create", "focus", "item", "restore"]),
+    context: new Set([
+        "activity",
+        "aggregate",
+        "context",
+        "ctx",
+        "duplicates",
+        "eval",
+        "get",
+        "help",
+        "list",
+        "list-all",
+        "list-blocked",
+        "list-canceled",
+        "list-closed",
+        "list-draft",
+        "list-in-progress",
+        "list-open",
+        "next",
+        "search",
+        "stats",
+    ]),
+    lifecycle: new Set([
+        "claim",
+        "close",
+        "close-many",
+        "close-task",
+        "delete",
+        "pause-task",
+        "release",
+        "start-task",
+        "update",
+        "update-many",
+    ]),
+    evidence: new Set([
+        "append",
+        "comments",
+        "docs",
+        "events",
+        "files",
+        "history",
+        "history-author-acknowledge",
+        "history-compact",
+        "history-redact",
+        "history-repair",
+        "learnings",
+        "notes",
+    ]),
+    graph: new Set(["deps", "graph", "plan"]),
+    quality: new Set([
+        "assurance",
+        "contracts",
+        "test",
+        "test-all",
+        "validate",
+    ]),
+    automation: new Set(["event", "meet", "remind"]),
+});
+const EXTENSION_COMMANDS = new Set([
+    "extension",
+    "install",
+    "package",
+    "packages",
+    "upgrade",
+]);
+/** Resolve one command's stable capability family. */
+export function resolvePmCommandCapabilityFamily(command) {
+    const normalized = command.trim().toLowerCase();
+    for (const [family, commands] of Object.entries(COMMANDS_BY_FAMILY)) {
+        if (commands.has(normalized))
+            return family;
+    }
+    return EXTENSION_COMMANDS.has(normalized) ? "extensions" : "internal";
+}
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -53,7 +139,7 @@ const STANDARD_COMMANDS = new Set([
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
-export const PM_COMMAND_VISIBILITY_CONTRACTS = Object.freeze([
+export const PM_COMMAND_CAPABILITY_CONTRACTS = Object.freeze([
     ...PM_CORE_COMMAND_NAMES.map((command) => ({
         command,
         tier: CORE_COMMANDS.has(command)
@@ -61,24 +147,31 @@ export const PM_COMMAND_VISIBILITY_CONTRACTS = Object.freeze([
             : STANDARD_COMMANDS.has(command)
                 ? "standard"
                 : "full",
+        family: resolvePmCommandCapabilityFamily(command),
     })),
     {
         command: "completion-statuses",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-tags",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-types",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "test-runs-worker",
         tier: "internal",
+        family: "internal",
     },
 ]);
+/** Backward-compatible tier-only projection of the capability contract. */
+export const PM_COMMAND_VISIBILITY_CONTRACTS = PM_COMMAND_CAPABILITY_CONTRACTS;
 const TIER_ORDER = {
     core: 0,
     standard: 1,
@@ -95,6 +188,10 @@ export function listPmCommandsForTier(tier) {
     const maximum = TIER_ORDER[tier];
     return PM_COMMAND_VISIBILITY_CONTRACTS.filter((entry) => entry.tier !== "internal" && TIER_ORDER[entry.tier] <= maximum).map((entry) => entry.command);
 }
+/** Return commands in one capability family, preserving contract order. */
+export function listPmCommandsForFamily(family) {
+    return PM_COMMAND_CAPABILITY_CONTRACTS.filter((entry) => entry.family === family).map((entry) => entry.command);
+}
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */
 export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
     pm_append: "append",
@@ -217,17 +314,17 @@ export const PM_MCP_PROMPT_CONTRACTS = Object.freeze([
 ]);
 /** Render the generated command visibility reference used by docs drift gates. */
 export function renderPmCommandVisibilityMarkdown() {
-    const rows = PM_COMMAND_VISIBILITY_CONTRACTS.map(({ command, tier }) => `| \`${command}\` | ${tier} |`);
+    const rows = PM_COMMAND_CAPABILITY_CONTRACTS.map(({ command, tier, family }) => `| \`${command}\` | ${tier} | ${family} |`);
     return [
         "# Generated agent command surface",
         "",
-        "This file is generated from `PM_COMMAND_VISIBILITY_CONTRACTS`. Do not edit it manually.",
+        "This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.",
         "",
-        "| Command | Minimum visibility tier |",
-        "| --- | --- |",
+        "| Command | Minimum visibility tier | Capability family |",
+        "| --- | --- | --- |",
         ...rows,
         "",
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=6fc2cd04-2fe4-5a0e-944d-fab0f86509e2
+//# debugId=dd74bc56-9971-59b9-8d2b-a6cc78b0a650

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;