@unbrained/pm-cli 2026.8.16 → 2026.8.18

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

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!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]="c82d9b50-274f-585d-be0e-9a0c5067b9e9")}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]="1d9df714-a6dc-5dc3-b2ff-c9325f91a443")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -136,6 +136,7 @@ export const LIST_FILTER_FLAG_CONTRACTS = withCursorSemantics([
     { flag: "--for", value_name: "intent" },
     { flag: "--token-budget", aliases: ["--token_budget"] },
     { flag: "--status", list: true },
+    { flag: "--all", value_type: "boolean" },
     { flag: "--type", list: true },
     { flag: "--tag", aliases: ["--tags"], list: true },
     { flag: "--priority", list: true },
@@ -1416,6 +1417,7 @@ export const EVENTS_FLAG_CONTRACTS = [
     { flag: "--author", repeatable: true },
     { flag: "--item", repeatable: true },
     { flag: "--limit", value_type: "number" },
+    { flag: "--cursor-mode", value_name: "batch|row" },
     { flag: "--full" },
     { flag: "--provenance" },
     { flag: "--provenance-summary" },
@@ -1636,9 +1638,7 @@ export function toUniqueFlagContracts(contracts) {
 function withSubcommandGlobalFlags(contracts) {
     return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
 }
-const LIST_COMMAND_FLAG_ALIASES = [
-    "list",
-    "list-all",
+const FIXED_STATUS_LIST_COMMAND_ALIASES = [
     "list-draft",
     "list-open",
     "list-in-progress",
@@ -1646,6 +1646,8 @@ const LIST_COMMAND_FLAG_ALIASES = [
     "list-closed",
     "list-canceled",
 ];
+const FIXED_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status" && contract.flag !== "--all");
+const ALL_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status");
 // Single-token command (plus the `list`/`cal`/`ctx`/`templates` aliases) → its
 // dedicated flag-contract table. Lookups fall back to the subcommand-global set,
 // so tokens absent here (`reindex`, `help`, or any unknown command) degrade to
@@ -1653,9 +1655,11 @@ const LIST_COMMAND_FLAG_ALIASES = [
 // plain object) keeps an untrusted command token from ever resolving an inherited
 // member such as `constructor` or `toString`.
 const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
-    ...LIST_COMMAND_FLAG_ALIASES.map((command) => [
+    ["list", LIST_FILTER_FLAG_CONTRACTS],
+    ["list-all", ALL_STATUS_LIST_FLAG_CONTRACTS],
+    ...FIXED_STATUS_LIST_COMMAND_ALIASES.map((command) => [
         command,
-        LIST_FILTER_FLAG_CONTRACTS,
+        FIXED_STATUS_LIST_FLAG_CONTRACTS,
     ]),
     ["templates", CREATE_FLAG_CONTRACTS],
     ["cal", CALENDAR_FLAG_CONTRACTS],
@@ -1821,4 +1825,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=c82d9b50-274f-585d-be0e-9a0c5067b9e9
+//# debugId=1d9df714-a6dc-5dc3-b2ff-c9325f91a443

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

@@ -0,0 +1,70 @@
+/**
+ * @module sdk/cli-contracts/grammar-contracts
+ *
+ * Declares and verifies the agent-facing noun–verb grammar. The destination
+ * census is intentionally exact: live command contracts are compared with
+ * this checked-in table in both directions so adding or removing a command
+ * cannot silently bypass the architecture decision.
+ */
+import type { PmCommandAliasContract } from "./command-aliases.js";
+/** Canonical top-level domains an agent must retain to route pm operations. */
+export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
+/** Shared verbs whose meaning transfers across domain nouns. */
+export declare const PM_CLI_SHARED_VERBS: readonly ["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"];
+/** Why a current command is permitted while the grammar migration proceeds. */
+export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
+/** Exact destination decision for one command emitted by runtime contracts. */
+export interface PmCommandDestinationContract {
+    /** Current executable command path. */
+    command: string;
+    /** Canonical noun that owns the capability. */
+    noun: (typeof PM_CLI_GRAMMAR_NOUNS)[number];
+    /** Canonical noun-first invocation or family destination. */
+    target: string;
+    /** Why the current spelling remains in the executable surface. */
+    disposition: PmCommandDestinationDisposition;
+    /** PM item or package identifier owning the disposition. */
+    owner: string;
+    /** Reason required only for a deliberate keep-as-is exception. */
+    reason?: string;
+}
+/** Checked-in exhaustive destination census for core and known package commands. */
+export declare const PM_COMMAND_DESTINATION_CONTRACTS: readonly PmCommandDestinationContract[];
+/** Immutable grammar policy used by contracts and the CI gate. */
+export declare const PM_CLI_GRAMMAR_CONTRACT: {
+    readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
+    readonly shared_verbs: readonly ["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"];
+    readonly scope_before_verb: true;
+    readonly visible_top_level_ceiling: 69;
+    readonly ceiling_raise_requires_pm_item: true;
+};
+/** One self-correcting grammar-gate finding. */
+export interface PmCliGrammarFinding {
+    /** Stable diagnostic category suitable for automated remediation. */
+    code: "alias_target_missing" | "duplicate_destination" | "missing_destination" | "stale_destination" | "unknown_noun" | "visible_surface_ceiling_exceeded";
+    /** Exact command or alias spelling that violated the contract. */
+    spelling: string;
+    /** Human-readable explanation of the violated invariant. */
+    message: string;
+    /** Closest canonical invocation or corrective policy action. */
+    nearest_target: string;
+}
+/** Deterministic conformance report for the live command and alias surfaces. */
+export interface PmCliGrammarReport {
+    /** Whether every checked grammar invariant passed. */
+    ok: boolean;
+    /** Number of normalized live command paths evaluated. */
+    command_count: number;
+    /** Number of checked-in destination-census rows. */
+    destination_count: number;
+    /** Number of declared aliases omitted from default discovery. */
+    hidden_alias_count: number;
+    /** Number of distinct visible non-package single-token command paths. */
+    visible_top_level_count: number;
+    /** Maximum visible single-token command paths permitted by the ADR. */
+    visible_top_level_ceiling: number;
+    /** Self-correcting conformance diagnostics, empty when `ok` is true. */
+    findings: PmCliGrammarFinding[];
+}
+/** Verify exhaustive census parity, noun ownership, alias targets, and growth. */
+export declare function verifyPmCliGrammar(commands: readonly string[], aliases?: readonly PmCommandAliasContract[]): PmCliGrammarReport;

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