@unbrained/pm-cli 2026.8.17 → 2026.8.19

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

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

package/dist/sdk/cli-contracts/commander-mutation-options.js

@@ -1,6 +1,6 @@
 /** Creates commander option registration contracts using the validated operation inputs. */
 
-!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]="f7e87e15-b5f3-53ab-86e2-768e94d5d329")}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]="93ce68bd-3140-5361-a6d0-bc60c7304a29")}catch(e){}}();
 export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     {
         target: "title",
@@ -501,17 +501,29 @@ export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Seed linked file entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Seed linked test entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -989,17 +1001,29 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Append linked file path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Append linked test command=<value>,path=<value>,scope=<project|global>,timeout_seconds=<n>,pm_context_mode=<schema|tracker|auto> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -1055,4 +1079,4 @@ export const UPDATE_COMMANDER_STRING_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_
 /** Public contract for update commander repeatable option contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.filter((entry) => entry.repeatable === true).map((entry) => ({ target: entry.target, keys: entry.keys }));
 //# sourceMappingURL=commander-mutation-options.js.map
-//# debugId=f7e87e15-b5f3-53ab-86e2-768e94d5d329
+//# debugId=93ce68bd-3140-5361-a6d0-bc60c7304a29

package/dist/sdk/cli-contracts/commander-types.js

@@ -1,6 +1,6 @@
 /** Public contract for list commander string option contracts, shared by SDK and presentation-layer consumers. */
 
-!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]="3b9b9ebe-8d98-5983-8257-b7b77c7e6194")}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]="5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8")}catch(e){}}();
 export const LIST_COMMANDER_STRING_OPTION_CONTRACTS = [
     { target: "status", keys: ["status"] },
     { target: "type", keys: ["type"] },
@@ -147,13 +147,14 @@ export function readFirstValueFromCommanderOptions(options, contract) {
 }
 /** Implements read string array from commander options for the public runtime surface of this module. */
 export function readStringArrayFromCommanderOptions(options, contract) {
+    const values = [];
     for (const key of contract.keys) {
         const candidate = options[key];
         if (Array.isArray(candidate)) {
-            return candidate;
+            values.push(...candidate.filter((value) => typeof value === "string"));
         }
     }
-    return undefined;
+    return values.length > 0 ? values : undefined;
 }
 //# sourceMappingURL=commander-types.js.map
-//# debugId=3b9b9ebe-8d98-5983-8257-b7b77c7e6194
+//# debugId=5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8

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

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

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

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

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

@@ -1,3 +1,4 @@
+import { type PmPositionalActionContract } from "./grammar-contracts.js";
 /** A single CLI flag's contract: its canonical `--flag`, optional short form, aliases, value metadata, and repeat/list semantics. One source of truth shared by Commander registration, argv normalization, shell completion, and the `pm contracts` command so every surface agrees on the flag vocabulary. */
 export interface CliFlagContract {
     /** Value that configures or reports flag for this contract. */
@@ -214,6 +215,10 @@ export declare const CONTRACTS_FLAG_CONTRACTS: CliFlagContract[];
 export declare const COMPLETION_FLAG_CONTRACTS: CliFlagContract[];
 /** Deduplicates flag contracts by their `flag`/`short`/`aliases` identity, preserving first-seen order. Used when merging the shared subcommand-global flags into a command's own contracts so a flag declared by both surfaces is registered only once. */
 export declare function toUniqueFlagContracts(contracts: CliFlagContract[]): CliFlagContract[];
+/** Resolve every positional action's accepted flags against one parent contract. */
+export declare function resolvePmPositionalActionFlagContracts(actions?: readonly PmPositionalActionContract[]): Array<readonly [string, CliFlagContract[]]>;
+/** Validated positional action flag entries shared by registration and contracts. */
+export declare const PM_POSITIONAL_ACTION_FLAG_CONTRACTS: (readonly [string, CliFlagContract[]])[];
 /** Returns whether a normalized command path owns a concrete core flag-contract row. Surface-less commands such as `help` intentionally return false, while positional virtual paths such as `workspace snapshot create` return true. */
 export declare function hasSubcommandFlagContractsForCommand(commandName: string | undefined): boolean;
 /** Resolves the flag contracts a given command (or list/extension subcommand) accepts, merged with the shared subcommand-global flags. Returns the global set for unknown or surface-less commands so completion and validation degrade gracefully. */

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

@@ -7,9 +7,10 @@
  * 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]="505e9b6b-a62a-5981-8862-619624246170")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
+import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
 function normalizeFlagAliasKey(flag) {
     if (!flag.startsWith("--")) {
         return flag;
@@ -136,6 +137,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 },
@@ -1138,8 +1140,8 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--unset" },
     { flag: "--clear-deps" },
@@ -1239,8 +1241,8 @@ export const UPDATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--reminder" },
     { flag: "--event" },
@@ -1416,6 +1418,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" },
@@ -1634,11 +1637,35 @@ export function toUniqueFlagContracts(contracts) {
     return unique;
 }
 function withSubcommandGlobalFlags(contracts) {
-    return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
+    const byCanonicalFlag = new Map();
+    for (const contract of [...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]) {
+        const canonicalFlag = normalizeFlagAliasKey(contract.flag);
+        const prior = byCanonicalFlag.get(canonicalFlag);
+        const { aliases: declaredAliases, ...contractWithoutAliases } = contract;
+        const aliases = normalizeUniqueStringList([
+            ...(declaredAliases ?? []),
+            ...(contract.flag === canonicalFlag ? [] : [contract.flag]),
+        ]).filter((alias) => alias !== canonicalFlag);
+        const normalizedContract = {
+            ...contractWithoutAliases,
+            flag: canonicalFlag,
+            ...(aliases.length > 0 ? { aliases } : {}),
+        };
+        const mergedAliases = normalizeUniqueStringList([
+            ...(prior?.aliases ?? []),
+            ...(normalizedContract.aliases ?? []),
+        ]);
+        byCanonicalFlag.set(canonicalFlag, prior === undefined
+            ? normalizedContract
+            : {
+                ...prior,
+                ...normalizedContract,
+                ...(mergedAliases.length > 0 ? { aliases: mergedAliases } : {}),
+            });
+    }
+    return withFlagAliasMetadata([...byCanonicalFlag.values()]);
 }
-const LIST_COMMAND_FLAG_ALIASES = [
-    "list",
-    "list-all",
+const FIXED_STATUS_LIST_COMMAND_ALIASES = [
     "list-draft",
     "list-open",
     "list-in-progress",
@@ -1646,6 +1673,45 @@ 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");
+function indexCliFlagContracts(contracts) {
+    const index = new Map();
+    for (const contract of contracts) {
+        for (const spelling of [contract.flag, ...(contract.aliases ?? [])]) {
+            const matches = index.get(spelling) ?? [];
+            matches.push(contract);
+            index.set(spelling, matches);
+        }
+    }
+    return index;
+}
+const PLAN_FLAG_CONTRACT_INDEX = indexCliFlagContracts(PLAN_FLAG_CONTRACTS);
+const ASSURANCE_FLAG_CONTRACT_INDEX = indexCliFlagContracts(ASSURANCE_FLAG_CONTRACTS);
+const POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT = new Map([
+    ["assurance", ASSURANCE_FLAG_CONTRACT_INDEX],
+    ["plan", PLAN_FLAG_CONTRACT_INDEX],
+    ["workspace snapshot", indexCliFlagContracts(WORKSPACE_FLAG_CONTRACTS)],
+]);
+/** Resolve every positional action's accepted flags against one parent contract. */
+export function resolvePmPositionalActionFlagContracts(actions = PM_POSITIONAL_ACTION_CONTRACTS) {
+    return actions.map(({ command, parent, accepted_flags: acceptedFlags }) => {
+        const parentFlagIndex = POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT.get(parent);
+        if (!parentFlagIndex) {
+            throw new Error(`Positional action ${command} has no flag-contract index for ${parent}.`);
+        }
+        const selected = acceptedFlags.map((acceptedFlag) => {
+            const matches = parentFlagIndex.get(acceptedFlag) ?? [];
+            if (matches.length !== 1) {
+                throw new Error(`Positional action ${command} accepted flag ${acceptedFlag} does not resolve to exactly one ${parent} flag contract.`);
+            }
+            return matches[0];
+        });
+        return [command, selected];
+    });
+}
+/** Validated positional action flag entries shared by registration and contracts. */
+export const PM_POSITIONAL_ACTION_FLAG_CONTRACTS = resolvePmPositionalActionFlagContracts();
 // 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 +1719,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],
@@ -1719,6 +1787,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["telemetry", TELEMETRY_FLAG_CONTRACTS],
     ["health", HEALTH_FLAG_CONTRACTS],
     ["assurance", ASSURANCE_FLAG_CONTRACTS],
+    ...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,
     ["validate", VALIDATE_FLAG_CONTRACTS],
     ["gc", GC_FLAG_CONTRACTS],
     ["stats", STATS_FLAG_CONTRACTS],
@@ -1747,6 +1816,7 @@ const EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND = new Map([
     ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
     ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
     ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
+    ["list", EXTENSION_CATALOG_FLAG_CONTRACTS],
     ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
     ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
     ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
@@ -1772,11 +1842,12 @@ export function hasSubcommandFlagContractsForCommand(commandName) {
         lifecycleSubcommand !== undefined &&
         extraParts.length === 0 &&
         (lifecycleSubcommand === "init" ||
+            lifecycleSubcommand === "scaffold" ||
             EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND.has(lifecycleSubcommand)));
 }
 /** Resolves the flag contracts an `extension`/`package <subcommand>` lifecycle invocation accepts. `init` carries the package-only `--declarative` flag, so `package`/`packages init` resolve to the package init table while `extension init` resolves to the extension init table; every other lifecycle subcommand shares one table, and an unknown subcommand falls back to globals-only. */
 function resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand) {
-    if (lifecycleSubcommand === "init") {
+    if (lifecycleSubcommand === "init" || lifecycleSubcommand === "scaffold") {
         // `--declarative` is package-only, so `package init` / `packages init` carry it.
         return rootCommand === "extension"
             ? EXTENSION_INIT_FLAG_CONTRACTS
@@ -1821,4 +1892,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=c82d9b50-274f-585d-be0e-9a0c5067b9e9
+//# debugId=505e9b6b-a62a-5981-8862-619624246170

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

@@ -0,0 +1,55 @@
+import { type PmCommandCapabilityFamily } from "../agent-capability-contracts.js";
+/** Stable value kinds used by the public flag lexicon. */
+export type PmFlagValueKind = "boolean" | "string" | "number" | "list";
+/** One canonical command-flag concept and every accepted compatibility alias. */
+export interface PmFlagLexiconEntry {
+    /** Canonical command path. */
+    command: string;
+    /** Command capability family. */
+    family: PmCommandCapabilityFamily;
+    /** Stable semantic concept identifier. */
+    concept: string;
+    /** Canonical long spelling emitted by generated surfaces. */
+    flag: string;
+    /** Accepted compatibility spellings that must never become canonical rows. */
+    aliases: readonly string[];
+    /** Parsed value shape. */
+    value_kind: PmFlagValueKind;
+}
+/** Ratcheted canonical flag budget for one command. */
+export interface PmCommandFlagBudget {
+    /** Canonical command path. */
+    command: string;
+    /** Current canonical flag count. */
+    current: number;
+    /** Maximum count accepted by the repository gate. */
+    maximum: number;
+}
+/** One fail-closed lexicon or budget violation. */
+export interface PmFlagLexiconFinding {
+    /** Stable finding code. */
+    code: "alias_collision" | "budget_exceeded" | "duplicate_canonical_flag" | "inconsistent_concept_kind" | "missing_budget" | "stale_budget";
+    /** Canonical command path. */
+    command: string;
+    /** Human-readable finding detail. */
+    detail: string;
+}
+/** Complete verification receipt for a flag lexicon corpus. */
+export interface PmFlagLexiconReport {
+    /** Whether every invariant and ratchet passed. */
+    ok: boolean;
+    /** Number of canonical command-flag rows checked. */
+    entry_count: number;
+    /** Number of command budgets checked. */
+    budget_count: number;
+    /** Stable ordered findings. */
+    findings: readonly PmFlagLexiconFinding[];
+}
+/** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
+export declare function listPmFlagLexicon(): readonly PmFlagLexiconEntry[];
+/** Return persisted no-growth ratchets with current counts derived from the canonical vocabulary. */
+export declare function listPmCommandFlagBudgets(): readonly PmCommandFlagBudget[];
+/** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
+export declare function verifyPmFlagLexicon(entries?: readonly PmFlagLexiconEntry[], budgets?: readonly PmCommandFlagBudget[]): PmFlagLexiconReport;
+/** Render a compact, generated family and command budget reference. Persisted budget rows are initialized to an explicit fallback so stale rows remain renderable. */
+export declare function renderPmFlagLexiconMarkdown(): string;