@unbrained/pm-cli 2026.5.31 → 2026.6.6

package/dist/sdk/cli-contracts.js

@@ -1,5 +1,5 @@
 
-!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]="b98193ee-1196-5e27-b732-d15db107a7e4")}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]="ed7e453d-9d75-5c91-8de4-990f9ddf155d")}catch(e){}}();
 export { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, 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";
 // PM_* enum/guard contracts and the bulk tool-parameter property/metadata data
@@ -7,9 +7,9 @@ export { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEAT
 // sites (sdk/index.ts, mcp/server.ts, commands/contracts.ts, completion.ts, …)
 // keep importing everything from "./cli-contracts.js" unchanged.
 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_TOOL_ACTIONS, isPmToolAction, isPmExtensionCapabilityContract, isPmExtensionServiceNameContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, } from "./cli-contracts/enum-contracts.js";
-export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_DEDUPE_AUDIT_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_NORMALIZE_FILTER_OPTION_CONTRACTS, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_DEPS_OPTION_CONTRACTS, } from "./cli-contracts/tool-option-contracts.js";
+export { TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_DEDUPE_AUDIT_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_NORMALIZE_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, } from "./cli-contracts/tool-option-contracts.js";
 import { PM_TOOL_ACTIONS } from "./cli-contracts/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_NORMALIZE_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, } from "./cli-contracts/tool-option-contracts.js";
+import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_NORMALIZE_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./cli-contracts/tool-option-contracts.js";
 import { PM_TOOL_PARAMETER_PROPERTIES, PM_TOOL_PARAMETER_METADATA, PLAN_ACTION_PARAMETER_PROPERTIES, PLAN_ACTION_PARAMETER_METADATA, } from "./cli-contracts/tool-parameter-tables.js";
 function normalizeUniqueStringList(values) {
     return [...new Set(Array.from(values).filter((value) => value.trim().length > 0))];
@@ -79,6 +79,11 @@ export const LIST_FILTER_FLAG_CONTRACTS = [
     { flag: "--priority" },
     { flag: "--deadline-before" },
     { flag: "--deadline-after" },
+    { flag: "--updated-after" },
+    { flag: "--updated-before" },
+    { flag: "--created-after" },
+    { flag: "--created-before" },
+    { flag: "--ids", list: true },
     { flag: "--assignee" },
     { flag: "--assignee-filter" },
     { flag: "--assignee_filter" },
@@ -204,6 +209,7 @@ export const HISTORY_FLAG_CONTRACTS = [
     { flag: "--compact" },
     { flag: "--full" },
     { flag: "--diff" },
+    { flag: "--field" },
     { flag: "--verify" },
 ];
 export const HISTORY_REDACT_FLAG_CONTRACTS = [
@@ -226,6 +232,11 @@ export const SCHEMA_FLAG_CONTRACTS = [
     { flag: "--default-status", aliases: ["--default_status"] },
     { flag: "--folder" },
     { flag: "--alias" },
+    // --role is a repeatable Commander collect flag (NOT a comma-list contract),
+    // mirroring --alias; list:false keeps the bootstrap coalescer from corrupting
+    // values.
+    { flag: "--role" },
+    { flag: "--order" },
     { flag: "--author" },
     { flag: "--force" },
 ];
@@ -240,7 +251,7 @@ export const PLAN_FLAG_CONTRACTS = [
     { flag: "--harness" },
     { flag: "--mode" },
     { flag: "--resume-context", aliases: ["--resume_context"] },
-    { flag: "--tags", list: true },
+    { flag: "--tags", aliases: ["--tag"], list: true },
     { flag: "--priority" },
     { flag: "--body" },
     { flag: "--claim" },
@@ -280,6 +291,7 @@ export const PLAN_FLAG_CONTRACTS = [
 ];
 export const INIT_FLAG_CONTRACTS = [
     { flag: "--preset" },
+    { flag: "--type-preset" },
     { flag: "--defaults", short: "-y", aliases: ["--yes"] },
     { flag: "--author" },
     { flag: "--agent-guidance" },
@@ -332,6 +344,51 @@ export const EXTENSION_FLAG_CONTRACTS = [
     { flag: "--strict-exit" },
     { flag: "--fail-on-warn" },
 ];
+export const EXTENSION_INIT_FLAG_CONTRACTS = [
+    { flag: "--project" },
+    { flag: "--local" },
+    { flag: "--global" },
+];
+export const EXTENSION_INSTALL_FLAG_CONTRACTS = [
+    { flag: "--project" },
+    { flag: "--local" },
+    { flag: "--global" },
+    { flag: "--gh" },
+    { flag: "--github" },
+    { flag: "--ref" },
+];
+export const EXTENSION_UNINSTALL_FLAG_CONTRACTS = EXTENSION_INIT_FLAG_CONTRACTS;
+export const EXTENSION_EXPLORE_FLAG_CONTRACTS = EXTENSION_INIT_FLAG_CONTRACTS;
+export const EXTENSION_ADOPT_ALL_FLAG_CONTRACTS = EXTENSION_INIT_FLAG_CONTRACTS;
+export const EXTENSION_ACTIVATE_FLAG_CONTRACTS = EXTENSION_INIT_FLAG_CONTRACTS;
+export const EXTENSION_DEACTIVATE_FLAG_CONTRACTS = EXTENSION_INIT_FLAG_CONTRACTS;
+export const EXTENSION_MANAGE_FLAG_CONTRACTS = [
+    ...EXTENSION_INIT_FLAG_CONTRACTS,
+    { flag: "--runtime-probe" },
+    { flag: "--fix-managed-state" },
+];
+export const EXTENSION_RELOAD_FLAG_CONTRACTS = [
+    ...EXTENSION_INIT_FLAG_CONTRACTS,
+    { flag: "--watch" },
+];
+export const EXTENSION_DOCTOR_FLAG_CONTRACTS = [
+    ...EXTENSION_INIT_FLAG_CONTRACTS,
+    { flag: "--detail" },
+    { flag: "--trace" },
+    { flag: "--fix-managed-state" },
+    { flag: "--strict-exit" },
+    { flag: "--fail-on-warn" },
+];
+export const EXTENSION_CATALOG_FLAG_CONTRACTS = [
+    ...EXTENSION_INIT_FLAG_CONTRACTS,
+    { flag: "--fields", list: true },
+];
+export const EXTENSION_ADOPT_FLAG_CONTRACTS = [
+    ...EXTENSION_INIT_FLAG_CONTRACTS,
+    { flag: "--gh" },
+    { flag: "--github" },
+    { flag: "--ref" },
+];
 export const INSTALL_FLAG_CONTRACTS = [
     { flag: "--project" },
     { flag: "--local" },
@@ -370,6 +427,41 @@ export const CLOSE_FLAG_CONTRACTS = [
     { flag: "--actual-result", aliases: ["--actual_result", "--actual"] },
     { flag: "--force" },
 ];
+// close-many shares update-many's `--filter-*` scoping family and close's
+// inline closure-validation fields. The shared close reason is required for the
+// audited bulk close (each matched item routes through runClose semantics).
+export const CLOSE_MANY_FLAG_CONTRACTS = [
+    { flag: "--filter-status", list: true },
+    { flag: "--filter-type" },
+    { flag: "--filter-tag" },
+    { flag: "--filter-priority" },
+    { flag: "--filter-deadline-before" },
+    { flag: "--filter-deadline-after" },
+    { flag: "--filter-updated-after" },
+    { flag: "--filter-updated-before" },
+    { flag: "--filter-created-after" },
+    { flag: "--filter-created-before" },
+    { flag: "--filter-assignee" },
+    { flag: "--filter-assignee-filter" },
+    { flag: "--filter-assignee_filter" },
+    { flag: "--filter-parent" },
+    { flag: "--filter-sprint" },
+    { flag: "--filter-release" },
+    { flag: "--ids", list: true },
+    { flag: "--limit" },
+    { flag: "--offset" },
+    { flag: "--reason" },
+    { flag: "--resolution" },
+    { flag: "--expected-result", aliases: ["--expected_result", "--expected"] },
+    { flag: "--actual-result", aliases: ["--actual_result", "--actual"] },
+    { flag: "--validate-close" },
+    { flag: "--author" },
+    { flag: "--message" },
+    { flag: "--force" },
+    { flag: "--dry-run" },
+    { flag: "--rollback" },
+    { flag: "--no-checkpoint" },
+];
 export const APPEND_FLAG_CONTRACTS = [
     { flag: "--body", short: "-b" },
     { flag: "--author" },
@@ -455,6 +547,9 @@ export const TEST_ALL_FLAG_CONTRACTS = [
     { flag: "--check-context" },
     { flag: "--auto-pm-context" },
 ];
+export const TELEMETRY_FLAG_CONTRACTS = [
+    { flag: "--limit" },
+];
 export const TEST_RUNS_FLAG_CONTRACTS = [
     { flag: "--status" },
     { flag: "--limit" },
@@ -467,6 +562,9 @@ export const GC_FLAG_CONTRACTS = [
     { flag: "--dry-run" },
     { flag: "--scope" },
 ];
+export const STATS_FLAG_CONTRACTS = [
+    { flag: "--storage" },
+];
 export const HEALTH_FLAG_CONTRACTS = [
     { flag: "--strict-directories" },
     { flag: "--strict-exit" },
@@ -497,6 +595,7 @@ export const VALIDATE_FLAG_CONTRACTS = [
     { flag: "--verbose-diagnostics" },
     { flag: "--strict-exit" },
     { flag: "--fail-on-warn" },
+    { flag: "--fix-hints" },
     { flag: "--check-history-drift" },
     { flag: "--check-command-references" },
 ];
@@ -511,7 +610,7 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--schedule_preset" },
     { short: "-s", flag: "--status" },
     { short: "-p", flag: "--priority" },
-    { flag: "--tags", list: true },
+    { flag: "--tags", aliases: ["--tag"], list: true },
     // NOT list:true — these use Commander's repeatable collector. Marking them
     // list:true would make the bootstrap coalescer comma-join repeated
     // occurrences (`--add-tags '["a","b"]' --add-tags c` -> `["a","b"],c`),
@@ -574,6 +673,7 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--dep" },
     { flag: "--type-option" },
     { flag: "--type_option" },
+    { flag: "--field" },
     { flag: "--reminder" },
     { flag: "--event" },
     { flag: "--comment" },
@@ -603,7 +703,7 @@ export const UPDATE_FLAG_CONTRACTS = [
     { flag: "--close_reason" },
     { short: "-p", flag: "--priority" },
     { flag: "--type" },
-    { flag: "--tags", list: true },
+    { flag: "--tags", aliases: ["--tag"], list: true },
     // NOT list:true — Commander's repeatable collector accumulates these, so
     // bootstrap coalescing must not comma-join repeated occurrences (it would
     // corrupt JSON-array values like `--add-tags '["a","b"]' --add-tags c`).
@@ -677,6 +777,7 @@ export const UPDATE_FLAG_CONTRACTS = [
     { flag: "--event" },
     { flag: "--type-option" },
     { flag: "--type_option" },
+    { flag: "--field" },
     { flag: "--unset" },
     { flag: "--clear-deps" },
     { flag: "--clear-comments" },
@@ -701,12 +802,17 @@ export const UPDATE_MANY_FLAG_CONTRACTS = [
     { flag: "--filter-priority" },
     { flag: "--filter-deadline-before" },
     { flag: "--filter-deadline-after" },
+    { flag: "--filter-updated-after" },
+    { flag: "--filter-updated-before" },
+    { flag: "--filter-created-after" },
+    { flag: "--filter-created-before" },
     { flag: "--filter-assignee" },
     { flag: "--filter-assignee-filter" },
     { flag: "--filter-assignee_filter" },
     { flag: "--filter-parent" },
     { flag: "--filter-sprint" },
     { flag: "--filter-release" },
+    { flag: "--ids", list: true },
     { flag: "--limit" },
     { flag: "--offset" },
     { flag: "--dry-run" },
@@ -717,7 +823,7 @@ export const UPDATE_MANY_FLAG_CONTRACTS = [
     { short: "-b", flag: "--body" },
     { short: "-p", flag: "--priority" },
     { flag: "--type" },
-    { flag: "--tags", list: true },
+    { flag: "--tags", aliases: ["--tag"], list: true },
     // NOT list:true — Commander's repeatable collector accumulates these, so
     // bootstrap coalescing must not comma-join repeated occurrences (it would
     // corrupt JSON-array values like `--add-tags '["a","b"]' --add-tags c`).
@@ -905,6 +1011,7 @@ export const SEARCH_FLAG_CONTRACTS = [
     { flag: "--full" },
     { flag: "--fields", list: true },
     { flag: "--limit" },
+    { flag: "--status", list: true },
     { flag: "--type" },
     { flag: "--tag" },
     { flag: "--priority" },
@@ -952,7 +1059,6 @@ const LIST_COMMAND_NAME_CONTRACTS = new Set([
     "list-canceled",
 ]);
 const NO_SURFACE_COMMAND_NAME_CONTRACTS = new Set([
-    "stats",
     "reindex",
     "help",
 ]);
@@ -985,6 +1091,39 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
     if (normalized === "test-runs-worker") {
         return withSubcommandGlobalFlags(TEST_RUNS_FLAG_CONTRACTS);
     }
+    const [rootCommand, lifecycleSubcommand, ...extraParts] = normalized.split(/\s+/);
+    if ((rootCommand === "extension" || rootCommand === "package" || rootCommand === "packages") &&
+        lifecycleSubcommand &&
+        extraParts.length === 0) {
+        switch (lifecycleSubcommand) {
+            case "init":
+                return withSubcommandGlobalFlags(EXTENSION_INIT_FLAG_CONTRACTS);
+            case "install":
+                return withSubcommandGlobalFlags(EXTENSION_INSTALL_FLAG_CONTRACTS);
+            case "uninstall":
+                return withSubcommandGlobalFlags(EXTENSION_UNINSTALL_FLAG_CONTRACTS);
+            case "explore":
+                return withSubcommandGlobalFlags(EXTENSION_EXPLORE_FLAG_CONTRACTS);
+            case "manage":
+                return withSubcommandGlobalFlags(EXTENSION_MANAGE_FLAG_CONTRACTS);
+            case "reload":
+                return withSubcommandGlobalFlags(EXTENSION_RELOAD_FLAG_CONTRACTS);
+            case "doctor":
+                return withSubcommandGlobalFlags(EXTENSION_DOCTOR_FLAG_CONTRACTS);
+            case "catalog":
+                return withSubcommandGlobalFlags(EXTENSION_CATALOG_FLAG_CONTRACTS);
+            case "adopt":
+                return withSubcommandGlobalFlags(EXTENSION_ADOPT_FLAG_CONTRACTS);
+            case "adopt-all":
+                return withSubcommandGlobalFlags(EXTENSION_ADOPT_ALL_FLAG_CONTRACTS);
+            case "activate":
+                return withSubcommandGlobalFlags(EXTENSION_ACTIVATE_FLAG_CONTRACTS);
+            case "deactivate":
+                return withSubcommandGlobalFlags(EXTENSION_DEACTIVATE_FLAG_CONTRACTS);
+            default:
+                return withSubcommandGlobalFlags([]);
+        }
+    }
     switch (normalized) {
         case "init":
             return withSubcommandGlobalFlags(INIT_FLAG_CONTRACTS);
@@ -1030,6 +1169,8 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
             return withSubcommandGlobalFlags(UPDATE_MANY_FLAG_CONTRACTS);
         case "close":
             return withSubcommandGlobalFlags(CLOSE_FLAG_CONTRACTS);
+        case "close-many":
+            return withSubcommandGlobalFlags(CLOSE_MANY_FLAG_CONTRACTS);
         case "delete":
             return withSubcommandGlobalFlags(DELETE_FLAG_CONTRACTS);
         case "append":
@@ -1050,12 +1191,16 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
             return withSubcommandGlobalFlags(TEST_FLAG_CONTRACTS);
         case "test-all":
             return withSubcommandGlobalFlags(TEST_ALL_FLAG_CONTRACTS);
+        case "telemetry":
+            return withSubcommandGlobalFlags(TELEMETRY_FLAG_CONTRACTS);
         case "health":
             return withSubcommandGlobalFlags(HEALTH_FLAG_CONTRACTS);
         case "validate":
             return withSubcommandGlobalFlags(VALIDATE_FLAG_CONTRACTS);
         case "gc":
             return withSubcommandGlobalFlags(GC_FLAG_CONTRACTS);
+        case "stats":
+            return withSubcommandGlobalFlags(STATS_FLAG_CONTRACTS);
         case "contracts":
             return withSubcommandGlobalFlags(CONTRACTS_FLAG_CONTRACTS);
         case "claim":
@@ -1115,6 +1260,20 @@ const NORMALIZE_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     "allowAuditUpdate",
     "force",
 ]);
+const CLOSE_MANY_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
+    ...TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS.map((entry) => entry.param),
+    "reason",
+    "resolution",
+    "expectedResult",
+    "actualResult",
+    "validateClose",
+    "dryRun",
+    "rollback",
+    "noCheckpoint",
+    "author",
+    "message",
+    "force",
+]);
 const CONTEXT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
     ...TOOL_CONTEXT_OPTION_CONTRACTS.map((entry) => entry.param),
     "past",
@@ -1152,7 +1311,7 @@ const SEARCH_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
 ]);
 const AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS = ["author", "message", "force"];
 const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
-    init: { optional: ["prefix", "preset", "defaults", "author", "agentGuidance", "withPackages"] },
+    init: { optional: ["prefix", "preset", "typePreset", "defaults", "author", "agentGuidance", "withPackages", "verbose"] },
     config: {
         required: ["scope", "configAction"],
         optional: ["key", "value", "criterion", "clearCriteria", "format", "policy"],
@@ -1167,7 +1326,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "extension-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
     "extension-reload": { optional: ["scope", "watch"] },
     "extension-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
-    "extension-catalog": { optional: ["scope"] },
+    "extension-catalog": { optional: ["scope", "fields"] },
     "extension-adopt": { required: ["target"], optional: ["scope", "github", "ref"] },
     "extension-adopt-all": { optional: ["scope"] },
     "extension-activate": { required: ["target"], optional: ["scope"] },
@@ -1209,7 +1368,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "package-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
     "package-reload": { optional: ["scope", "watch"] },
     "package-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
-    "package-catalog": { optional: ["scope"] },
+    "package-catalog": { optional: ["scope", "fields"] },
     "package-adopt": { required: ["target"], optional: ["scope", "github", "ref"] },
     "package-adopt-all": { optional: ["scope"] },
     "package-activate": { required: ["target"], optional: ["scope"] },
@@ -1282,9 +1441,17 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         optional: ["dryRun", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS],
     },
     schema: {
-        required: ["subcommand", "name"],
-        // No --message: schema add-type writes a config file, not item history.
-        optional: ["description", "defaultStatus", "folder", "alias", "author", "force"],
+        required: ["subcommand"],
+        // No --message: schema mutations write config files, not item history.
+        optional: ["name", "description", "defaultStatus", "folder", "alias", "role", "order", "author", "force"],
+        conditionalRequired: [
+            { property: "subcommand", value: "show", required: ["name"] },
+            { property: "subcommand", value: "add-type", required: ["name"] },
+            { property: "subcommand", value: "remove-type", required: ["name"] },
+            // add-status/remove-status pass the status id as `name`.
+            { property: "subcommand", value: "add-status", required: ["name"] },
+            { property: "subcommand", value: "remove-status", required: ["name"] },
+        ],
     },
     plan: {
         required: ["subcommand"],
@@ -1348,6 +1515,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     "update-many": { optional: UPDATE_MANY_CONTRACT_PARAMETER_KEYS },
     normalize: { optional: NORMALIZE_CONTRACT_PARAMETER_KEYS },
     close: { required: ["id", "text"], optional: ["validateClose", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
+    "close-many": { optional: CLOSE_MANY_CONTRACT_PARAMETER_KEYS },
     delete: { required: ["id"], optional: ["dryRun", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
     append: { required: ["id", "body"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
     comments: {
@@ -1444,6 +1612,9 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "autoPmContext",
         ],
     },
+    telemetry: {
+        optional: ["subcommand", "limit"],
+    },
     "test-runs-list": {
         optional: ["status", "limit"],
     },
@@ -1462,7 +1633,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
         required: ["runId"],
         optional: ["author"],
     },
-    stats: {},
+    stats: { optional: ["storage"] },
     health: {
         optional: [
             "strictDirectories",
@@ -1495,6 +1666,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "verboseDiagnostics",
             "strictExit",
             "failOnWarn",
+            "fixHints",
             "checkHistoryDrift",
             "checkCommandReferences",
         ],
@@ -1579,6 +1751,19 @@ function buildActionScopedToolSchema(action) {
             required: [...requiredFields],
         }));
     }
+    if (contract.conditionalRequired && contract.conditionalRequired.length > 0) {
+        schema.allOf = contract.conditionalRequired.map((entry) => ({
+            if: {
+                properties: {
+                    [entry.property]: { const: entry.value },
+                },
+                required: [entry.property],
+            },
+            then: {
+                required: entry.required,
+            },
+        }));
+    }
     return schema;
 }
 // Building the full MCP tool-parameter schemas (one variant per action) is only
@@ -1602,11 +1787,32 @@ 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 the contract tests
+ * all bind to one constant instead of re-typing the `"4.0.2"` literal (pm-r9sz).
+ * 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.0.2";
+/**
+ * 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.0.0";
 export const PM_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(() => ({
     $schema: "https://json-schema.org/draft/2020-12/schema",
-    $id: "https://schema.unbrained.dev/pm-cli/tool-parameters-v4.schema.json",
+    $id: `https://schema.unbrained.dev/pm-cli/tool-parameters-v${PM_TOOL_PARAMETERS_SCHEMA_MAJOR}.schema.json`,
     title: "pm-cli tool parameters (action-scoped strict schema)",
-    "x-schema-version": "4.0.1",
+    "x-schema-version": PM_TOOL_PARAMETERS_SCHEMA_VERSION,
     type: "object",
     oneOf: PM_TOOL_ACTIONS.map((action) => buildActionScopedToolSchema(action)),
 }));
@@ -1647,7 +1853,7 @@ function buildProviderCompatibleToolSchema() {
     }
     return {
         title: "pm-cli tool parameters (provider-compatible flat schema)",
-        "x-schema-version": "1.0.0",
+        "x-schema-version": PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION,
         type: "object",
         additionalProperties: false,
         required: ["action"],
@@ -1656,4 +1862,4 @@ function buildProviderCompatibleToolSchema() {
 }
 export const PM_PROVIDER_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(buildProviderCompatibleToolSchema);
 //# sourceMappingURL=cli-contracts.js.map
-//# debugId=b98193ee-1196-5e27-b732-d15db107a7e4
+//# debugId=ed7e453d-9d75-5c91-8de4-990f9ddf155d