@unbrained/pm-cli 2026.8.17 → 2026.8.19

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

@@ -5,7 +5,7 @@
  */
 import { type GlobalOptions, type ExtensionRegistrationRegistry, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions, type RuntimeFieldRegistry, readSettings } from "../runtime-primitives.js";
 import { type McpToolContract } from "../../mcp/tool-definitions.js";
-import { PM_TOOL_ACTIONS, type CliFlagContract, type CommanderOptionAliasContract, type PmCommandOutputBudgetContract } from "../cli-contracts.js";
+import { PM_TOOL_ACTIONS, type CliFlagContract, type CommanderOptionAliasContract, type PmCommandOutputBudgetContract, type PmCommandAliasContract } from "../cli-contracts.js";
 import { type ListCommandName, type ListProjectionMode } from "../query/list.js";
 import { type PmContextIntentContract } from "../context-intent-contracts.js";
 import { type PmReadOutputSurfaceContract } from "../read-output-contracts.js";
@@ -14,6 +14,7 @@ import { type PmCommandVisibilityTier } from "../agent-capability-contracts.js";
 import type { PmErrorCodeContract } from "../error-code-catalog.js";
 import { type PmCommandOutputEnvelopeContract } from "../output-contracts.js";
 import { type PmCommandExitContract, type PmCommandExitOutcomeContract } from "./command-exit-contracts.js";
+import { type PmCommandPositionalContract, type PmCommandDestinationContract } from "./grammar-contracts.js";
 /** Documents the contracts command options payload exchanged by command, SDK, and package integrations. */
 export interface ContractsCommandOptions {
     /** Value that configures or reports action for this contract. */
@@ -38,6 +39,7 @@ interface CommandFlagSurface {
     canonical_command?: string;
     visibility?: PmCommandVisibilityTier;
     flags: CliFlagContract[];
+    positionals?: PmCommandPositionalContract["slots"];
     flag_invocations?: CliFlagInvocationContract[];
     provider?: "core" | "extension" | "mixed";
     extension_sources?: Array<{
@@ -45,9 +47,14 @@ interface CommandFlagSurface {
         name: string;
     }>;
 }
-interface CommandAliasSurface {
+/** Grouped command-alias projection retained for backward-compatible consumers. */
+export interface CommandAliasSurface {
+    /** Canonical command path shared by the grouped aliases. */
     canonical: string;
+    /** Accepted alternate spellings for the canonical path. */
     aliases: string[];
+    /** Per-spelling lifecycle, visibility, replacement, and ownership metadata. */
+    contracts?: PmCommandAliasContract[];
 }
 /** Machine-readable projection behavior for one list command. */
 interface ListCommandProjectionSurface {
@@ -93,6 +100,20 @@ export interface ContractsResult {
     list_projections?: ListCommandProjectionSurface[];
     /** Value that configures or reports command aliases for this contract. */
     command_aliases?: CommandAliasSurface[];
+    /** Noun–verb routing policy and exhaustive current-command destinations. */
+    grammar_contracts?: {
+        nouns: readonly string[];
+        shared_verbs: readonly string[];
+        scope_before_verb: boolean;
+        visible_top_level_ceiling: number;
+        ceiling_raise_requires_pm_item: boolean;
+        positional_shape_budget: number;
+        positional_shape_count: number;
+        positional_action_count: number;
+        positional_action_parents: readonly string[];
+        positional_signatures?: readonly PmCommandPositionalContract[];
+        destinations?: readonly PmCommandDestinationContract[];
+    };
     /** Value that configures or reports commander aliases for this contract. */
     commander_aliases?: Record<string, CommanderOptionAliasContract[]>;
     /** Value that configures or reports extension commands for this contract. */
@@ -236,10 +257,12 @@ interface CommandSummarySurface {
     command: string;
     aliases?: string[];
     intent: string;
-    intent_source: "command" | "description" | "generated";
+    /** Non-default provenance in compact output; exhaustive provenance in full output. */
+    intent_source?: "command" | "description" | "generated";
     flags?: string[];
     default_max_estimated_tokens: number;
-    default_max_estimated_tokens_by_format: {
+    /** Full-projection format detail; compact summaries retain the canonical default only. */
+    default_max_estimated_tokens_by_format?: {
         toon: number;
         json: number;
     };
@@ -283,9 +306,14 @@ declare function normalizeCommandForRuntimeFieldFlags(command: string): string;
 declare function toRuntimeLongFlagToken(token: string): string | null;
 declare function toRuntimeShortFlagToken(token: string): string | null;
 declare function buildRuntimeFieldFlagContracts(fieldRegistry: RuntimeFieldRegistry): Map<string, CliFlagContract[]>;
+/** Build the executable alias projection from a command catalog and alias table. */
+export declare function buildCommandAliasSurface(commands: string[], aliasContracts?: readonly PmCommandAliasContract[]): CommandAliasSurface[];
 declare function attachCreateRequiredOptionContracts(schema: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>;
 declare function readContractsSettings(pmRoot: string, readSettingsFn?: typeof readSettings): Promise<Awaited<ReturnType<typeof readSettings>>>;
-declare function buildCommandSummarySurface(commands: readonly string[], extensionContracts?: readonly ExtensionCommandContract[]): CommandSummarySurface[];
+declare function buildCommandSummarySurface(commands: readonly string[], extensionContracts?: readonly ExtensionCommandContract[], options?: {
+    includeFormatBudgets?: boolean;
+    includeIntentProvenance?: boolean;
+}): CommandSummarySurface[];
 declare function buildCommandOutputContracts(commands: readonly string[]): NonNullable<ContractsResult["command_output_contracts"]>;
 declare function buildCommandExitContractGroups(commands: readonly string[]): NonNullable<ContractsResult["command_exit_contracts"]>["command_sets"];
 /** Implements run contracts for the public runtime surface of this module. */

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

@@ -4,10 +4,11 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8cdd82c3-979e-5f7f-bc72-592c7e55f11c")}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]="30d9b9dd-f0a1-578e-90d6-3c019e0435b5")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
-import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
+import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_DEPRECATED_TOOL_ACTIONS, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, PM_COMMAND_ALIAS_CONTRACTS, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
+import { PM_POSITIONAL_ACTION_FLAG_CONTRACTS } from "./flag-contracts.js";
 import { GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES, GOVERNANCE_CREATE_MODE_DEFAULT_VALUES, GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES, GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES, } from "../../types.js";
 import { BRIEF_LIST_FIELDS, DEFAULT_COMPACT_LIST_FIELDS, LIST_COMMAND_DEFAULT_PROJECTIONS, } from "../query/list.js";
 import { getActiveContextIntentContracts, } from "../context-intent-contracts.js";
@@ -19,6 +20,7 @@ import { resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
 import { PM_COMMAND_EXIT_OUTCOME_CONTRACTS, resolvePmCommandExitContract, } from "./command-exit-contracts.js";
 import { BUILTIN_RELATIONSHIP_KINDS } from "../relationship-kinds/contract.js";
 import { ASSURANCE_GATE_TRIGGERS, ASSURANCE_MEASUREMENT_SOURCE_KINDS, } from "../governance/assurance.js";
+import { PM_CLI_GRAMMAR_CONTRACT, PM_COMMAND_DESTINATION_CONTRACTS, PM_COMMAND_POSITIONAL_CONTRACTS, PM_POSITIONAL_ACTION_CONTRACTS, positionalShapeKey, resolvePmCommandPositionalContract, } from "./grammar-contracts.js";
 const AGENT_BOOTSTRAP_FLAGS = new Map([
     [
         "claim",
@@ -409,6 +411,7 @@ const CORE_COMMAND_FLAG_CONTRACT_ENTRIES = [
     ["validate", VALIDATE_FLAG_CONTRACTS],
     ["health", HEALTH_FLAG_CONTRACTS],
     ["assurance", ASSURANCE_FLAG_CONTRACTS],
+    ...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,
     ["contracts", CONTRACTS_FLAG_CONTRACTS],
     ["completion", COMPLETION_FLAG_CONTRACTS],
     ["activity", ACTIVITY_FLAG_CONTRACTS],
@@ -459,7 +462,8 @@ function actionDescriptorMatchesSelectedCommand(descriptor, selectedCommand) {
         if (commandPath === selectedCommand) {
             return true;
         }
-        return commandPath.startsWith(`${selectedCommand} `);
+        return (commandPath.startsWith(`${selectedCommand} `) ||
+            selectedCommand.startsWith(`${commandPath} `));
     });
 }
 function splitCommandPathAliases(commandPath) {
@@ -1183,6 +1187,7 @@ function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap
                 ? {
                     canonical_command: canonicalSummaryCommand(command),
                     visibility: resolvePmCommandVisibilityTier(canonicalSummaryCommand(command)),
+                    positionals: resolvePmCommandPositionalContract(command)?.slots ?? [],
                     flag_invocations: enrichCliFlagInvocationContracts(command, flags),
                 }
                 : {}),
@@ -1192,12 +1197,40 @@ function buildCommandFlagSurface(commands, extensionFlagMap, runtimeFieldFlagMap
     })
         .sort((left, right) => left.command.localeCompare(right.command));
 }
-function buildCommandAliasSurface(commands) {
+/** Build the executable alias projection from a command catalog and alias table. */
+export function buildCommandAliasSurface(commands, aliasContracts = PM_COMMAND_ALIAS_CONTRACTS) {
     const commandSet = new Set(commands);
-    return CANONICAL_COMMAND_ALIASES.map((entry) => ({
-        canonical: entry.canonical,
-        aliases: entry.aliases.filter((alias) => commandSet.has(alias)),
-    })).filter((entry) => commandSet.has(entry.canonical) && entry.aliases.length > 0);
+    const grouped = new Map();
+    for (const entry of CANONICAL_COMMAND_ALIASES) {
+        const aliases = entry.aliases.filter((alias) => commandSet.has(alias));
+        grouped.set(entry.canonical, {
+            canonical: entry.canonical,
+            aliases,
+            contracts: [],
+        });
+    }
+    for (const contract of aliasContracts) {
+        if (!commandSet.has(contract.canonical)) {
+            continue;
+        }
+        if (contract.registration === "commander" &&
+            !commandSet.has(contract.alias)) {
+            continue;
+        }
+        const entry = grouped.get(contract.canonical) ?? {
+            canonical: contract.canonical,
+            aliases: [],
+            contracts: [],
+        };
+        if (!entry.aliases.includes(contract.alias)) {
+            entry.aliases.push(contract.alias);
+        }
+        entry.contracts.push(contract);
+        grouped.set(contract.canonical, entry);
+    }
+    return [...grouped.values()]
+        .map(({ contracts, ...entry }) => contracts.length === 0 ? entry : { ...entry, contracts })
+        .sort((left, right) => left.canonical.localeCompare(right.canonical));
 }
 function buildCommanderAliasSurface() {
     return {
@@ -1382,6 +1415,11 @@ function collectContractsActionDescriptors(selection, mergedExtensionContracts)
     const actionDescriptors = collectActionContractDescriptors(mergedExtensionContracts, {
         includePackageOwnedActions: shouldIncludePackageOwnedActions(selection),
     });
+    if (selection.selectedAction === undefined &&
+        selection.selectedCommand === undefined) {
+        const deprecatedActions = new Set(PM_DEPRECATED_TOOL_ACTIONS);
+        return actionDescriptors.filter((descriptor) => !deprecatedActions.has(descriptor.action));
+    }
     if (shouldIncludePackageOwnedActions(selection) &&
         selection.selectedCommand !== undefined &&
         PACKAGE_OWNED_COMMANDS.has(selection.selectedCommand) &&
@@ -1604,8 +1642,13 @@ function resolveContractsCommands(selection, actionContext) {
     }
     return actionContext.commandCatalog;
 }
-function resolveOutputCommands(_selection, commands) {
-    return commands;
+function resolveOutputCommands(selection, commands) {
+    if (selection.selectedCommand !== undefined ||
+        selection.selectedAction !== undefined) {
+        return commands;
+    }
+    const hiddenAliases = new Set(PM_COMMAND_ALIAS_CONTRACTS.filter((contract) => contract.hidden && contract.lifecycle === "deprecated").map((contract) => contract.alias));
+    return commands.filter((command) => !hiddenAliases.has(command));
 }
 function canonicalSummaryCommand(command) {
     const rootCommand = command.split(" ")[0];
@@ -1677,7 +1720,9 @@ function summarizeCommandIntent(command, extensionContracts) {
         intent_source: "generated",
     };
 }
-function buildCommandSummarySurface(commands, extensionContracts = []) {
+function buildCommandSummarySurface(commands, extensionContracts = [], options = {}) {
+    const includeFormatBudgets = options.includeFormatBudgets ?? true;
+    const includeIntentProvenance = options.includeIntentProvenance ?? true;
     return [...new Set(commands.map(normalizeCommandPath))]
         .filter((command) => command.length > 0)
         .sort((left, right) => left.localeCompare(right))
@@ -1704,12 +1749,19 @@ function buildCommandSummarySurface(commands, extensionContracts = []) {
         const intent = summarizeCommandIntent(command, extensionContracts);
         return {
             command,
-            ...intent,
+            intent: intent.intent,
+            ...(includeIntentProvenance || intent.intent_source !== "command"
+                ? { intent_source: intent.intent_source }
+                : {}),
             ...(flags.length > 0 ? { flags } : {}),
             default_max_estimated_tokens: budget.default_max_estimated_tokens,
-            default_max_estimated_tokens_by_format: {
-                ...budget.default_max_estimated_tokens_by_format,
-            },
+            ...(includeFormatBudgets
+                ? {
+                    default_max_estimated_tokens_by_format: {
+                        ...budget.default_max_estimated_tokens_by_format,
+                    },
+                }
+                : {}),
         };
     });
 }
@@ -1871,9 +1923,7 @@ function attachFlagContractsResult(result, selection, runtime, outputCommands, c
     else {
         result.command_flags_omitted_reason = "unfiltered_default_brief";
     }
-    if (commandAliases.length > 0) {
-        result.command_aliases = commandAliases;
-    }
+    result.command_aliases = commandAliases;
 }
 function attachCommanderAliasContractsResult(result, selection) {
     if (selection.schemaOnly ||
@@ -1890,13 +1940,32 @@ function attachCommanderAliasContractsResult(result, selection) {
         : "unfiltered_default_brief";
 }
 /** Attach the compact agent-facing command semantics shared by summary and full projections. */
-function attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts) {
-    result.command_summaries = buildCommandSummarySurface(outputCommands, extensionCommandContracts);
+function attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts, options) {
+    result.command_summaries = buildCommandSummarySurface(outputCommands, extensionCommandContracts, {
+        includeFormatBudgets: options.includeFormatBudgets,
+        includeIntentProvenance: options.includeIntentProvenance,
+    });
     result.output_policy = {
         token_estimate: "ceil(utf8_bytes / 4)",
         degradation_ladder: [...PM_OUTPUT_DEGRADATION_STEPS],
         allows_unbounded_opt_out: true,
     };
+    result.grammar_contracts = {
+        nouns: PM_CLI_GRAMMAR_CONTRACT.nouns,
+        shared_verbs: PM_CLI_GRAMMAR_CONTRACT.shared_verbs,
+        scope_before_verb: PM_CLI_GRAMMAR_CONTRACT.scope_before_verb,
+        visible_top_level_ceiling: PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling,
+        ceiling_raise_requires_pm_item: PM_CLI_GRAMMAR_CONTRACT.ceiling_raise_requires_pm_item,
+        positional_shape_budget: PM_CLI_GRAMMAR_CONTRACT.positional_shape_budget,
+        positional_shape_count: new Set(PM_COMMAND_POSITIONAL_CONTRACTS.map(({ slots }) => positionalShapeKey(slots))).size,
+        positional_action_count: PM_POSITIONAL_ACTION_CONTRACTS.length,
+        positional_action_parents: [
+            ...new Set(PM_POSITIONAL_ACTION_CONTRACTS.map(({ parent }) => parent)),
+        ].sort((left, right) => left.localeCompare(right)),
+        ...(options.includePositionalSignatures
+            ? { positional_signatures: PM_COMMAND_POSITIONAL_CONTRACTS }
+            : {}),
+    };
 }
 /** Implements run contracts for the public runtime surface of this module. */
 export async function runContracts(options, global) {
@@ -1910,13 +1979,18 @@ export async function runContracts(options, global) {
     const outputCommands = resolveOutputCommands(selection, commands);
     const result = createContractsResult(selection, schemaContext, actionContext, outputCommands);
     const extensionCommandContracts = resolveExtensionCommandContracts(selection, runtime, outputCommands);
+    const includeCommandDetails = selection.fullOutput || selection.selectedCommand !== undefined;
     if (selection.summary || selection.fullOutput) {
-        attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts);
+        attachAgentCommandContractsResult(result, outputCommands, extensionCommandContracts, {
+            includeFormatBudgets: includeCommandDetails,
+            includeIntentProvenance: includeCommandDetails,
+            includePositionalSignatures: includeCommandDetails,
+        });
     }
     if (selection.summary) {
         return result;
     }
-    const commandAliases = buildCommandAliasSurface(commands);
+    const commandAliases = buildCommandAliasSurface(actionContext.commandCatalog);
     if (!(selection.flagsOnly && !selection.fullOutput)) {
         attachRuntimeContractsResult(result, runtime, selection);
     }
@@ -1929,6 +2003,9 @@ export async function runContracts(options, global) {
             gate_triggers: [...ASSURANCE_GATE_TRIGGERS],
         };
     }
+    if (selection.fullOutput && result.grammar_contracts) {
+        result.grammar_contracts.destinations = PM_COMMAND_DESTINATION_CONTRACTS;
+    }
     // pm-4os2: snapshot the static MCP tool surface in the full projection so
     // `pnpm contracts:check` (CI static gate) fails on unintended inputSchema
     // drift in src/mcp/tool-definitions.ts.
@@ -1983,4 +2060,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=8cdd82c3-979e-5f7f-bc72-592c7e55f11c
+//# debugId=30d9b9dd-f0a1-578e-90d6-3c019e0435b5

package/dist/sdk/cli-contracts/tool-option-contracts.d.ts

@@ -3,7 +3,34 @@
  *
  * Defines SDK command-contract metadata for Tool Option Contracts.
  */
-import type { ToolOptionFlagContract } from "./flag-contracts.js";
+import type { CliFlagContract, ToolOptionFlagContract } from "./flag-contracts.js";
+/** One SDK/MCP parameter spelling that cannot be executed by the matching CLI. */
+export interface ToolOptionCliParityFinding {
+    /** Stable remediation category. */
+    code: "missing_cli_flag" | "missing_parameter_alias";
+    /** SDK/MCP parameter key. */
+    parameter: string;
+    /** Canonical CLI flag selected by the tool transport. */
+    flag: string;
+    /** Executable parameter-shaped flag expected by cross-surface callers. */
+    parameter_flag: string;
+}
+/** Fail-closed receipt for one tool option table and executable CLI flag table. */
+export interface ToolOptionCliParityReport {
+    /** Whether every mapping and cross-surface spelling is executable. */
+    ok: boolean;
+    /** Number of tool parameter mappings inspected. */
+    parameter_count: number;
+    /** Number of executable CLI flag contracts inspected. */
+    cli_flag_count: number;
+    /** Missing canonical flags or direct parameter aliases. */
+    findings: ToolOptionCliParityFinding[];
+}
+/**
+ * Verify that every declared tool parameter maps to a real CLI flag and that
+ * its kebab-case spelling is accepted either canonically or as an alias.
+ */
+export declare function verifyToolOptionCliParity(toolOptions: readonly ToolOptionFlagContract[], cliFlags: readonly CliFlagContract[]): ToolOptionCliParityReport;
 /** Public contract for tool list filter option contracts, shared by SDK and presentation-layer consumers. */
 export declare const TOOL_LIST_FILTER_OPTION_CONTRACTS: ToolOptionFlagContract[];
 /** Public contract for tool aggregate option contracts, shared by SDK and presentation-layer consumers. */

package/dist/sdk/cli-contracts/tool-option-contracts.js

@@ -1,6 +1,41 @@
-/** Returns fresh option contract objects so exported arrays cannot share mutable entries. */
+/**
+ * Verify that every declared tool parameter maps to a real CLI flag and that
+ * its kebab-case spelling is accepted either canonically or as an alias.
+ */
 
-!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]="e2028eff-b29e-5850-87b1-4a3e06f28964")}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]="88009976-e03f-5a67-b6fc-bf60240dde49")}catch(e){}}();
+export function verifyToolOptionCliParity(toolOptions, cliFlags) {
+    const findings = [];
+    for (const { param, flag } of toolOptions) {
+        const parameterFlag = `--${param.replace(/([a-z\d])([A-Z])/gu, "$1-$2").toLowerCase()}`;
+        const cliFlag = cliFlags.find((candidate) => candidate.flag === flag);
+        if (!cliFlag) {
+            findings.push({
+                code: "missing_cli_flag",
+                parameter: param,
+                flag,
+                parameter_flag: parameterFlag,
+            });
+            continue;
+        }
+        if (cliFlag.flag !== parameterFlag &&
+            !cliFlag.aliases?.includes(parameterFlag)) {
+            findings.push({
+                code: "missing_parameter_alias",
+                parameter: param,
+                flag,
+                parameter_flag: parameterFlag,
+            });
+        }
+    }
+    return {
+        ok: findings.length === 0,
+        parameter_count: toolOptions.length,
+        cli_flag_count: cliFlags.length,
+        findings,
+    };
+}
+/** Returns fresh option contract objects so exported arrays cannot share mutable entries. */
 function cloneOptionContracts(contracts) {
     return contracts.map((contract) => ({ ...contract }));
 }
@@ -424,4 +459,4 @@ export const TOOL_GRAPH_OPTION_CONTRACTS = [
     { param: "summary", flag: "--summary" },
 ];
 //# sourceMappingURL=tool-option-contracts.js.map
-//# debugId=e2028eff-b29e-5850-87b1-4a3e06f28964
+//# debugId=88009976-e03f-5a67-b6fc-bf60240dde49

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="4749819e-f2af-5a17-9d32-2e2770c497c3")}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]="e0314840-0dac-5966-8c4f-3a3e5db15688")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 import { ASSURANCE_DEFINITION_SCHEMA } from "./schemas/assurance-definition.js";
@@ -191,6 +191,7 @@ export const PM_TOOL_PARAMETER_PROPERTIES = {
     schedulePreset: { type: "string", enum: ["lightweight"] },
     status: { type: "string" },
     since: { type: "string", format: "date-time" },
+    cursorMode: { type: "string", enum: ["batch", "row"] },
     threshold: { type: "number", minimum: 0, maximum: 1 },
     filterStatus: { type: "string" },
     filterType: { type: "string" },
@@ -1951,6 +1952,10 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
             description: "Maximum mutation events returned, from 0 through 1000.",
             examples: [0, 100],
         },
+        cursorMode: {
+            description: "Cursor framing: batch returns one terminal next_cursor (default); row also adds a cursor to every event.",
+            examples: ["batch", "row"],
+        },
     },
     remind: {
         at: {
@@ -2067,4 +2072,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=4749819e-f2af-5a17-9d32-2e2770c497c3
+//# debugId=e0314840-0dac-5966-8c4f-3a3e5db15688

package/dist/sdk/cli-contracts/tool-schema.d.ts

@@ -91,14 +91,14 @@ export interface PmActionToolInputSchemaOptions {
  */
 export declare function buildPmActionToolInputSchema(action: PmToolAction, options?: PmActionToolInputSchemaOptions): Record<string, unknown>;
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and contract tests bind to one version constant. Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.7.0";
+export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.8.0";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
  */
 export declare const PM_TOOL_PARAMETERS_SCHEMA_MAJOR: string;
 /** Version of the provider-compatible flat tool-parameters schema (`PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`). Tracked separately from the strict schema because the flat projection evolves independently. */
-export declare const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION: "1.3.0";
+export declare const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION: "1.4.0";
 /** Public contract for pm tool parameters schema, shared by SDK and presentation-layer consumers. */
 export declare const PM_TOOL_PARAMETERS_SCHEMA: Record<string, unknown>;
 declare function toProviderCompatibleParameterDefinition(key: string, definition: unknown): Record<string, unknown>;

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="1d6089b2-ab59-59ad-a475-9a6ef1356b40")}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]="085c5e7b-97c1-5bc5-a95f-c6a17e709e97")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -205,6 +205,7 @@ const ACTIVITY_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
 ]);
 const LIST_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     ...TOOL_LIST_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    "all",
     "includeBody",
     "noTruncate",
     "strictRead",
@@ -212,6 +213,8 @@ const LIST_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "brief",
     "full",
 ]);
+const FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS = LIST_CONTRACT_PARAMETER_KEYS.filter((parameter) => parameter !== "all" && parameter !== "status");
+const ALL_STATUS_LIST_CONTRACT_PARAMETER_KEYS = LIST_CONTRACT_PARAMETER_KEYS.filter((parameter) => parameter !== "status");
 const LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS = [
     [
         { property: "today", schema: { const: true } },
@@ -475,31 +478,31 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-all": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: ALL_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-draft": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-open": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-in-progress": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-blocked": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-closed": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     "list-canceled": {
-        optional: LIST_CONTRACT_PARAMETER_KEYS,
+        optional: FIXED_STATUS_LIST_CONTRACT_PARAMETER_KEYS,
         mutuallyExclusiveWhen: LIST_WINDOW_MUTUALLY_EXCLUSIVE_GROUPS,
     },
     aggregate: { optional: AGGREGATE_CONTRACT_PARAMETER_KEYS },
@@ -538,6 +541,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "harness",
             "agentInstance",
             "provenanceFilter",
+            "cursorMode",
         ],
     },
     merge: {
@@ -1236,6 +1240,11 @@ function decorateToolParameterDefinition(key, definition) {
     };
 }
 function actionScopedToolParameterMetadata(action, key) {
+    if ((action === "list" || action.startsWith("list-")) && key === "all") {
+        return {
+            description: "Return items from every lifecycle status instead of the default active-status set.",
+        };
+    }
     if (action === "plan" &&
         Object.prototype.hasOwnProperty.call(PLAN_ACTION_PARAMETER_METADATA, key)) {
         return PLAN_ACTION_PARAMETER_METADATA[key];
@@ -1506,14 +1515,14 @@ function createLazyContractSchema(build) {
     });
 }
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and contract tests bind to one version constant. Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.7.0";
+export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.8.0";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
  */
 export const PM_TOOL_PARAMETERS_SCHEMA_MAJOR = PM_TOOL_PARAMETERS_SCHEMA_VERSION.split(".")[0];
 /** Version of the provider-compatible flat tool-parameters schema (`PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`). Tracked separately from the strict schema because the flat projection evolves independently. */
-export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.3.0";
+export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.4.0";
 /** Public contract for pm tool parameters schema, shared by SDK and presentation-layer consumers. */
 export const PM_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(() => ({
     $schema: "https://json-schema.org/draft/2020-12/schema",
@@ -1588,4 +1597,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=1d6089b2-ab59-59ad-a475-9a6ef1356b40
+//# debugId=085c5e7b-97c1-5bc5-a95f-c6a17e709e97

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

@@ -11,15 +11,16 @@
  * here.)
  */
 export type { CommanderOptionAliasContract, CommanderOptionRegistrationContract, } from "./cli-contracts/commander-types.js";
-export { EXECUTABLE_COMMAND_ALIASES } from "./cli-contracts/command-aliases.js";
+export { EXECUTABLE_COMMAND_ALIASES, PM_COMMAND_ALIAS_CONTRACTS, renderPmCommandAliasMigrationHint, resolvePmCommandAlias, type PmCommandAliasContract, type PmCommandAliasLifecycle, type PmCommandAliasRegistration, } from "./cli-contracts/command-aliases.js";
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "./cli-contracts/commander-types.js";
 export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, } from "./cli-contracts/commander-mutation-options.js";
-export { PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
+export { PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, PM_DEPRECATED_TOOL_ACTIONS, PM_DISCOVERABLE_TOOL_ACTIONS, PM_TOOL_ACTIONS, analyzePmToolActionParity, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
 export type { PmExtensionCapabilityContract, PmExtensionServiceNameContract, PmExtensionPolicyModeContract, PmExtensionTrustModeContract, PmExtensionSandboxProfileContract, PmExtensionPolicySurfaceContract, PmToolAction, } from "./cli-contracts/enum-contracts.js";
-export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, } from "./cli-contracts/tool-option-contracts.js";
+export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, verifyToolOptionCliParity, type ToolOptionCliParityFinding, type ToolOptionCliParityReport, } from "./cli-contracts/tool-option-contracts.js";
 export type { OptionsFromContracts, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmUpdateActionOptions, PmUpdateManyActionOptions, } from "./cli-contracts/typed-action-inputs.js";
 export type { CliFlagContract, ToolOptionFlagContract, } from "./cli-contracts/flag-contracts.js";
-export { withFlagAliasMetadata, compactFlagAliasContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
+export { PM_POSITIONAL_ACTION_CONTRACTS, type PmPositionalActionContract, } from "./cli-contracts/grammar-contracts.js";
+export { withFlagAliasMetadata, compactFlagAliasContracts, resolvePmPositionalActionFlagContracts, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, PLAN_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, ASSURANCE_FLAG_CONTRACTS, CREATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, CALENDAR_FLAG_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, CONTEXT_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, toCompletionFlagString, } from "./cli-contracts/flag-contracts.js";
 export type { PmActionSchemaContract } from "./cli-contracts/tool-schema.js";
 export { buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, resolvePmToolCustomFieldCollision, CLOSE_ACTION_OPTION_KEYS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA, _testOnlyCliContracts, } from "./cli-contracts/tool-schema.js";
 export type { PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, } from "./cli-contracts/tool-schema.js";