@unbrained/pm-cli 2026.8.17 → 2026.8.18

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

@@ -0,0 +1,345 @@
+/** Canonical top-level domains an agent must retain to route pm operations. */
+
+!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]="b959d41a-c0b6-55fe-a426-0be073f0511c")}catch(e){}}();
+export const PM_CLI_GRAMMAR_NOUNS = [
+    "item",
+    "list",
+    "context",
+    "search",
+    "graph",
+    "history",
+    "workspace",
+    "package",
+    "ops",
+    "plan",
+    "contracts",
+    "help",
+];
+/** Shared verbs whose meaning transfers across domain nouns. */
+export const PM_CLI_SHARED_VERBS = [
+    "activate",
+    "add",
+    "adopt",
+    "adopt-all",
+    "catalog",
+    "compact",
+    "complete",
+    "create",
+    "deactivate",
+    "delete",
+    "describe",
+    "doctor",
+    "edit",
+    "explore",
+    "import",
+    "init",
+    "inspect",
+    "install",
+    "list",
+    "manage",
+    "migrate",
+    "mutate",
+    "read",
+    "redact",
+    "reload",
+    "remove",
+    "repair",
+    "restore",
+    "run",
+    "show",
+    "uninstall",
+    "verify",
+];
+function destinationRows(noun, target, disposition, owner, commands) {
+    return commands.map((command) => ({
+        command,
+        noun,
+        target,
+        disposition,
+        owner,
+    }));
+}
+/** Checked-in exhaustive destination census for core and known package commands. */
+export const PM_COMMAND_DESTINATION_CONTRACTS = [
+    ...destinationRows("item", "item", "target_noun", "pm-pbyu", [
+        "item",
+        "item complete",
+        "item mutate",
+    ]),
+    ...destinationRows("item", "item", "consolidation", "pm-yql1", [
+        "append",
+        "claim",
+        "close",
+        "close-many",
+        "close-task",
+        "comments",
+        "copy",
+        "create",
+        "delete",
+        "docs",
+        "files",
+        "get",
+        "learnings",
+        "notes",
+        "pause-task",
+        "release",
+        "start-task",
+        "test",
+        "update",
+        "update-many",
+    ]),
+    ...destinationRows("list", "list", "target_noun", "pm-pfqi", ["list"]),
+    ...destinationRows("list", "list --group-by", "consolidation", "pm-xkgq", [
+        "aggregate",
+    ]),
+    ...destinationRows("context", "context", "target_noun", "pm-pbyu", [
+        "context",
+    ]),
+    ...destinationRows("context", "context", "consolidation", "pm-kcs4", [
+        "ctx",
+        "focus",
+        "next",
+    ]),
+    ...destinationRows("search", "search", "target_noun", "pm-pbyu", [
+        "search",
+    ]),
+    ...destinationRows("search", "search", "package_owned", "package:search-advanced", ["reindex", "search-advanced"]),
+    ...destinationRows("search", "search duplicates", "consolidation", "pm-3i9q8g", ["duplicates"]),
+    ...destinationRows("graph", "graph", "target_noun", "pm-pbyu", ["graph"]),
+    ...destinationRows("graph", "graph show", "consolidation", "pm-yql1", [
+        "deps",
+    ]),
+    ...destinationRows("history", "history", "target_noun", "pm-pbyu", [
+        "history",
+    ]),
+    ...destinationRows("history", "history", "consolidation", "pm-tqel", [
+        "activity",
+        "events",
+        "history-author-acknowledge",
+        "history-compact",
+        "history-redact",
+        "history-repair",
+        "merge",
+        "restore",
+    ]),
+    ...destinationRows("history", "history", "package_owned", "package:builtin-vcs-exemplar", [
+        "vcs abandon",
+        "vcs create",
+        "vcs log",
+        "vcs merge",
+        "vcs propose",
+        "vcs ref-create",
+        "vcs show",
+    ]),
+    ...destinationRows("workspace", "workspace", "target_noun", "pm-pbyu", [
+        "workspace",
+        "workspace snapshot",
+        "workspace snapshot create",
+        "workspace snapshot delete",
+        "workspace snapshot inspect",
+        "workspace snapshot list",
+        "workspace snapshot restore",
+    ]),
+    ...destinationRows("workspace", "workspace init", "consolidation", "pm-n7rr", ["init"]),
+    ...destinationRows("package", "package", "target_noun", "pm-pbyu", [
+        "package",
+        "package activate",
+        "package adopt",
+        "package adopt-all",
+        "package catalog",
+        "package deactivate",
+        "package describe",
+        "package doctor",
+        "package explore",
+        "package init",
+        "package install",
+        "package manage",
+        "package migrate",
+        "package reload",
+        "package uninstall",
+    ]),
+    ...destinationRows("package", "package", "consolidation", "pm-tnud", [
+        "extension",
+        "extension activate",
+        "extension adopt",
+        "extension adopt-all",
+        "extension catalog",
+        "extension deactivate",
+        "extension describe",
+        "extension doctor",
+        "extension explore",
+        "extension init",
+        "extension install",
+        "extension manage",
+        "extension migrate",
+        "extension reload",
+        "extension uninstall",
+        "install",
+        "packages",
+        "packages activate",
+        "packages adopt",
+        "packages adopt-all",
+        "packages catalog",
+        "packages deactivate",
+        "packages describe",
+        "packages doctor",
+        "packages explore",
+        "packages init",
+        "packages install",
+        "packages manage",
+        "packages migrate",
+        "packages reload",
+        "packages uninstall",
+        "upgrade",
+    ]),
+    ...destinationRows("package", "package", "package_owned", "package:beads", [
+        "beads import",
+    ]),
+    ...destinationRows("package", "package", "package_owned", "package:pm-changelog", ["changelog export", "changelog generate"]),
+    ...destinationRows("package", "package calendar", "package_owned", "pm-o3fh", ["event", "meet", "remind"]),
+    ...destinationRows("ops", "ops", "consolidation", "pm-6apl", [
+        "assurance",
+        "config",
+        "eval",
+        "gc",
+        "health",
+        "profile",
+        "schema",
+        "stats",
+        "telemetry",
+        "test-all",
+        "validate",
+    ]),
+    ...destinationRows("plan", "plan", "target_noun", "pm-pbyu", ["plan"]),
+    ...destinationRows("contracts", "contracts", "target_noun", "pm-pbyu", [
+        "contracts",
+    ]),
+    ...destinationRows("help", "help", "target_noun", "pm-pbyu", ["help"]),
+    ...destinationRows("help", "help", "package_owned", "package:builtin-guide-shell", [
+        "completion",
+        "completion-statuses",
+        "completion-tags",
+        "completion-types",
+        "guide",
+    ]),
+];
+/** Immutable grammar policy used by contracts and the CI gate. */
+export const PM_CLI_GRAMMAR_CONTRACT = {
+    nouns: PM_CLI_GRAMMAR_NOUNS,
+    shared_verbs: PM_CLI_SHARED_VERBS,
+    scope_before_verb: true,
+    visible_top_level_ceiling: 69,
+    ceiling_raise_requires_pm_item: true,
+};
+function validateCommandDestinations(commands, destinationsByCommand, nounSet) {
+    return commands.flatMap((command) => {
+        const destinations = destinationsByCommand.get(command) ?? [];
+        if (destinations.length === 0) {
+            const separatorIndex = command.indexOf(" ");
+            const root = separatorIndex === -1 ? command : command.slice(0, separatorIndex);
+            return [
+                {
+                    code: "missing_destination",
+                    spelling: command,
+                    message: `Command \`${command}\` has no destination census row.`,
+                    nearest_target: nounSet.has(root) ? root : `ops ${command}`,
+                },
+            ];
+        }
+        const duplicateFinding = destinations.length > 1
+            ? [
+                {
+                    code: "duplicate_destination",
+                    spelling: command,
+                    message: `Command \`${command}\` has ${destinations.length} destination rows.`,
+                    nearest_target: destinations[0].target,
+                },
+            ]
+            : [];
+        return destinations.reduce((findings, destination) => {
+            if (destination.disposition === "keep_as_is" &&
+                (destination.reason?.trim().length ?? 0) === 0) {
+                findings.push({
+                    code: "missing_destination",
+                    spelling: command,
+                    message: `Command \`${command}\` is kept as-is without a documented reason.`,
+                    nearest_target: destination.target,
+                });
+            }
+            if (!nounSet.has(destination.noun)) {
+                findings.push({
+                    code: "unknown_noun",
+                    spelling: command,
+                    message: `Command \`${command}\` names undeclared noun \`${destination.noun}\`.`,
+                    nearest_target: destination.target,
+                });
+            }
+            return findings;
+        }, duplicateFinding);
+    });
+}
+function validateDestinationCensus(commandSet, destinations) {
+    return destinations
+        .filter((destination) => destination.disposition !== "package_owned" &&
+        !commandSet.has(destination.command))
+        .map((destination) => ({
+        code: "stale_destination",
+        spelling: destination.command,
+        message: `Destination row \`${destination.command}\` is absent from live contracts.`,
+        nearest_target: destination.target,
+    }));
+}
+function validateAliasTargets(aliases, commandSet) {
+    return aliases
+        .filter((alias) => !commandSet.has(alias.canonical))
+        .map((alias) => ({
+        code: "alias_target_missing",
+        spelling: alias.alias,
+        message: `Alias \`${alias.alias}\` targets missing canonical command \`${alias.canonical}\`.`,
+        nearest_target: alias.canonical_argv.join(" "),
+    }));
+}
+/** Implementation seam accepts an injected census for isolated conformance tests. */
+export function verifyPmCliGrammar(commands, aliases = [], destinations = PM_COMMAND_DESTINATION_CONTRACTS) {
+    const normalizedCommands = [
+        ...new Set(commands.map((command) => command.trim())),
+    ]
+        .filter((command) => command.length > 0)
+        .sort((left, right) => left.localeCompare(right));
+    const commandSet = new Set(normalizedCommands);
+    const nounSet = new Set(PM_CLI_GRAMMAR_NOUNS);
+    const destinationsByCommand = new Map();
+    for (const destination of destinations) {
+        const entries = destinationsByCommand.get(destination.command) ?? [];
+        entries.push(destination);
+        destinationsByCommand.set(destination.command, entries);
+    }
+    const findings = [
+        ...validateCommandDestinations(normalizedCommands, destinationsByCommand, nounSet),
+        ...validateDestinationCensus(commandSet, destinations),
+        ...validateAliasTargets(aliases, commandSet),
+    ];
+    const hiddenAliasNames = new Set(aliases.filter((alias) => alias.hidden).map((alias) => alias.alias));
+    const visibleTopLevelCount = new Set(normalizedCommands.filter((command) => !command.includes(" ") &&
+        !hiddenAliasNames.has(command) &&
+        !(destinationsByCommand.get(command) ?? []).some((destination) => destination.disposition === "package_owned"))).size;
+    if (visibleTopLevelCount > PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling) {
+        findings.push({
+            code: "visible_surface_ceiling_exceeded",
+            spelling: String(visibleTopLevelCount),
+            message: `Visible non-package top-level command count ${visibleTopLevelCount} exceeds ceiling ${PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling}.`,
+            nearest_target: "Declare the noun placement and tracked waiver before raising the ceiling.",
+        });
+    }
+    return {
+        ok: findings.length === 0,
+        command_count: normalizedCommands.length,
+        destination_count: destinations.length,
+        hidden_alias_count: aliases.filter((alias) => alias.hidden).length,
+        visible_top_level_count: visibleTopLevelCount,
+        visible_top_level_ceiling: PM_CLI_GRAMMAR_CONTRACT.visible_top_level_ceiling,
+        findings,
+    };
+}
+//# sourceMappingURL=grammar-contracts.js.map
+//# debugId=b959d41a-c0b6-55fe-a426-0be073f0511c

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 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. */
@@ -45,9 +46,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 +99,15 @@ 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;
+        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. */
@@ -283,6 +298,8 @@ 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[];

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

@@ -4,10 +4,10 @@
  * 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]="9a66a2a0-94be-595b-983d-347ec95af85e")}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 { 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 +19,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, } from "./grammar-contracts.js";
 const AGENT_BOOTSTRAP_FLAGS = new Map([
     [
         "claim",
@@ -1192,12 +1193,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 +1411,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 +1638,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];
@@ -1871,9 +1910,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 ||
@@ -1897,6 +1934,13 @@ function attachAgentCommandContractsResult(result, outputCommands, extensionComm
         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,
+    };
 }
 /** Implements run contracts for the public runtime surface of this module. */
 export async function runContracts(options, global) {
@@ -1916,7 +1960,7 @@ export async function runContracts(options, global) {
     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 +1973,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 +2030,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=8cdd82c3-979e-5f7f-bc72-592c7e55f11c
+//# debugId=9a66a2a0-94be-595b-983d-347ec95af85e

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>;