@unbrained/pm-cli 2026.6.24 → 2026.7.1

package/dist/cli-bundle/chunks/{chunk-OF7V47P3.js → chunk-HXTQJXWT.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]="358fc257-d2e2-5538-b106-a600db4ae795")}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]="43af9766-fa42-5af2-8e94-459bc0205f26")}catch(e){}}();
 import {
   KNOWN_EXTENSION_CAPABILITIES,
   KNOWN_EXTENSION_POLICY_MODES,
@@ -11,7 +11,7 @@ import {
   PLAN_MODE_VALUES,
   PLAN_STEP_LINK_KIND_VALUES,
   PLAN_STEP_STATUS_VALUES
-} from "./chunk-VSAABFGQ.js";
+} from "./chunk-7R4QEMZZ.js";
 
 // dist/sdk/cli-contracts/commander-types.js
 var LIST_COMMANDER_STRING_OPTION_CONTRACTS = [
@@ -99,6 +99,19 @@ var CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS = [
   { target: "activityLimit", keys: ["activityLimit", "activity_limit"] },
   { target: "staleThreshold", keys: ["staleThreshold", "stale_threshold"] }
 ];
+var NEXT_COMMANDER_STRING_OPTION_CONTRACTS = [
+  { target: "type", keys: ["type"] },
+  { target: "tag", keys: ["tag"] },
+  { target: "priority", keys: ["priority"] },
+  { target: "assignee", keys: ["assignee"] },
+  { target: "assigneeFilter", keys: ["assigneeFilter", "assignee_filter"] },
+  { target: "sprint", keys: ["sprint"] },
+  { target: "release", keys: ["release"] },
+  { target: "parent", keys: ["parent"] },
+  { target: "limit", keys: ["limit"] },
+  { target: "blockedLimit", keys: ["blockedLimit", "blocked_limit"] },
+  { target: "format", keys: ["format"] }
+];
 var ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS = [
   { target: "id", keys: ["id"] },
   { target: "op", keys: ["op"] },
@@ -691,11 +704,13 @@ var PM_CORE_COMMAND_NAMES = [
   "get",
   "search",
   "eval",
+  "next",
   "history",
   "history-redact",
   "history-repair",
   "history-compact",
   "schema",
+  "profile",
   "activity",
   "restore",
   "update",
@@ -778,11 +793,13 @@ var PM_TOOL_ACTIONS = [
   "ctx",
   "get",
   "search",
+  "next",
   "history",
   "history-redact",
   "history-repair",
   "history-compact",
   "schema",
+  "profile",
   "activity",
   "restore",
   "update",
@@ -813,1817 +830,257 @@ var PM_TOOL_ACTIONS = [
   "close-task"
 ];
 
-// dist/sdk/cli-contracts/tool-option-contracts.js
-var TOOL_LIST_FILTER_OPTION_CONTRACTS = [
-  { param: "status", flag: "--status" },
-  { param: "type", flag: "--type" },
-  { param: "tag", flag: "--tag" },
-  { param: "priority", flag: "--priority" },
-  { param: "deadlineBefore", flag: "--deadline-before" },
-  { param: "deadlineAfter", flag: "--deadline-after" },
-  { param: "updatedAfter", flag: "--updated-after" },
-  { param: "updatedBefore", flag: "--updated-before" },
-  { param: "createdAfter", flag: "--created-after" },
-  { param: "createdBefore", flag: "--created-before" },
-  { param: "ids", flag: "--ids" },
-  { param: "assignee", flag: "--assignee" },
-  { param: "assigneeFilter", flag: "--assignee-filter" },
-  { param: "parent", flag: "--parent" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" },
-  { param: "filterAcMissing", flag: "--filter-ac-missing" },
-  { param: "filterEstimatesMissing", flag: "--filter-estimates-missing" },
-  { param: "filterResolutionMissing", flag: "--filter-resolution-missing" },
-  { param: "filterMetadataMissing", flag: "--filter-metadata-missing" },
-  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
-  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
-  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
-  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
-  { param: "filterReleaseMissing", flag: "--filter-release-missing" },
-  { param: "hasNotes", flag: "--has-notes" },
-  { param: "noNotes", flag: "--no-notes" },
-  { param: "hasLearnings", flag: "--has-learnings" },
-  { param: "noLearnings", flag: "--no-learnings" },
-  { param: "hasFiles", flag: "--has-files" },
-  { param: "noFiles", flag: "--no-files" },
-  { param: "hasDocs", flag: "--has-docs" },
-  { param: "noDocs", flag: "--no-docs" },
-  { param: "hasTests", flag: "--has-tests" },
-  { param: "noTests", flag: "--no-tests" },
-  { param: "hasComments", flag: "--has-comments" },
-  { param: "noComments", flag: "--no-comments" },
-  { param: "hasDeps", flag: "--has-deps" },
-  { param: "noDeps", flag: "--no-deps" },
-  { param: "hasBody", flag: "--has-body" },
-  { param: "emptyBody", flag: "--empty-body" },
-  { param: "hasLinkedCommand", flag: "--has-linked-command" },
-  { param: "noLinkedCommand", flag: "--no-linked-command" },
-  { param: "limit", flag: "--limit" },
-  { param: "offset", flag: "--offset" },
-  { param: "fields", flag: "--fields" },
-  { param: "sort", flag: "--sort" },
-  { param: "order", flag: "--order" },
-  { param: "tree", flag: "--tree" },
-  { param: "treeDepth", flag: "--tree-depth" }
-];
-var TOOL_AGGREGATE_OPTION_CONTRACTS = [
-  { param: "groupBy", flag: "--group-by" },
-  { param: "sum", flag: "--sum" },
-  { param: "avg", flag: "--avg" },
-  { param: "status", flag: "--status" },
-  { param: "type", flag: "--type" },
-  { param: "tag", flag: "--tag" },
-  { param: "priority", flag: "--priority" },
-  { param: "deadlineBefore", flag: "--deadline-before" },
-  { param: "deadlineAfter", flag: "--deadline-after" },
-  { param: "assignee", flag: "--assignee" },
-  { param: "assigneeFilter", flag: "--assignee-filter" },
-  { param: "parent", flag: "--parent" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" }
+// dist/sdk/cli-contracts/string-lists.js
+function normalizeUniqueStringList(values) {
+  return [...new Set(Array.from(values, (value) => value.trim()).filter((value) => value.length > 0))];
+}
+
+// dist/sdk/cli-contracts/flag-contracts.js
+function normalizeFlagAliasKey(flag) {
+  if (!flag.startsWith("--")) {
+    return flag;
+  }
+  return `--${flag.slice(2).replaceAll("_", "-")}`;
+}
+function withFlagAliasMetadata(flagContracts) {
+  const aliasesByCanonical = /* @__PURE__ */ new Map();
+  for (const contract of flagContracts) {
+    const canonical = normalizeFlagAliasKey(contract.flag);
+    const bucket = aliasesByCanonical.get(canonical) ?? /* @__PURE__ */ new Set();
+    if (contract.flag !== canonical) {
+      bucket.add(contract.flag);
+    }
+    for (const alias of contract.aliases ?? []) {
+      if (alias !== canonical) {
+        bucket.add(alias);
+      }
+    }
+    aliasesByCanonical.set(canonical, bucket);
+  }
+  return flagContracts.map((contract) => {
+    const canonical = normalizeFlagAliasKey(contract.flag);
+    if (contract.flag !== canonical) {
+      return contract;
+    }
+    const aliases = normalizeUniqueStringList([
+      ...contract.aliases ?? [],
+      ...aliasesByCanonical.get(canonical)
+    ]).filter((alias) => alias !== canonical);
+    if (aliases.length === 0) {
+      return contract;
+    }
+    return {
+      ...contract,
+      aliases
+    };
+  });
+}
+function compactFlagAliasContracts(flagContracts) {
+  const withAliases = withFlagAliasMetadata(flagContracts);
+  const canonicalFlags = new Set(withAliases.map((contract) => contract.flag));
+  return withAliases.filter((contract) => {
+    const canonical = normalizeFlagAliasKey(contract.flag);
+    return contract.flag === canonical || !canonicalFlags.has(canonical);
+  });
+}
+var SUBCOMMAND_GLOBAL_FLAG_CONTRACTS = [
+  { flag: "--json" },
+  { flag: "--quiet" },
+  { flag: "--no-changed-fields" },
+  { flag: "--id-only" },
+  { flag: "--pm-path", aliases: ["--path"] },
+  { flag: "--no-extensions" },
+  { flag: "--no-pager" },
+  { flag: "--profile" },
+  { flag: "--help" }
 ];
-var TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS = [
-  { param: "mode", flag: "--mode" },
-  { param: "limit", flag: "--limit" },
-  { param: "threshold", flag: "--threshold" },
-  { param: "status", flag: "--status" },
-  { param: "type", flag: "--type" },
-  { param: "tag", flag: "--tag" },
-  { param: "priority", flag: "--priority" },
-  { param: "deadlineBefore", flag: "--deadline-before" },
-  { param: "deadlineAfter", flag: "--deadline-after" },
-  { param: "assignee", flag: "--assignee" },
-  { param: "assigneeFilter", flag: "--assignee-filter" },
-  { param: "parent", flag: "--parent" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" }
+var GLOBAL_FLAG_CONTRACTS = [
+  ...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS,
+  { flag: "--version" }
 ];
-var TOOL_SEARCH_FILTER_OPTION_CONTRACTS = [
-  { param: "matchMode", flag: "--match-mode" },
-  { param: "minScore", flag: "--min-score" },
-  { param: "count", flag: "--count", booleanish: true },
-  { param: "semanticWeight", flag: "--semantic-weight" },
-  { param: "status", flag: "--status" },
-  { param: "type", flag: "--type" },
-  { param: "tag", flag: "--tag" },
-  { param: "priority", flag: "--priority" },
-  { param: "deadlineBefore", flag: "--deadline-before" },
-  { param: "deadlineAfter", flag: "--deadline-after" },
-  { param: "updatedAfter", flag: "--updated-after" },
-  { param: "updatedBefore", flag: "--updated-before" },
-  { param: "createdAfter", flag: "--created-after" },
-  { param: "createdBefore", flag: "--created-before" },
-  { param: "assignee", flag: "--assignee" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" },
-  { param: "parent", flag: "--parent" },
-  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
-  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
-  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
-  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
-  { param: "filterReleaseMissing", flag: "--filter-release-missing" },
-  { param: "hasNotes", flag: "--has-notes" },
-  { param: "noNotes", flag: "--no-notes" },
-  { param: "hasLearnings", flag: "--has-learnings" },
-  { param: "noLearnings", flag: "--no-learnings" },
-  { param: "hasFiles", flag: "--has-files" },
-  { param: "noFiles", flag: "--no-files" },
-  { param: "hasDocs", flag: "--has-docs" },
-  { param: "noDocs", flag: "--no-docs" },
-  { param: "hasTests", flag: "--has-tests" },
-  { param: "noTests", flag: "--no-tests" },
-  { param: "hasComments", flag: "--has-comments" },
-  { param: "noComments", flag: "--no-comments" },
-  { param: "hasDeps", flag: "--has-deps" },
-  { param: "noDeps", flag: "--no-deps" },
-  { param: "hasBody", flag: "--has-body" },
-  { param: "emptyBody", flag: "--empty-body" },
-  { param: "hasLinkedCommand", flag: "--has-linked-command" },
-  { param: "noLinkedCommand", flag: "--no-linked-command" },
-  { param: "fields", flag: "--fields" },
-  { param: "limit", flag: "--limit" }
+var LIST_FILTER_FLAG_CONTRACTS = [
+  { flag: "--status", list: true },
+  { flag: "--type" },
+  { flag: "--tag", aliases: ["--tags"] },
+  { 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" },
+  { flag: "--parent" },
+  { flag: "--sprint" },
+  { flag: "--release" },
+  { flag: "--filter-ac-missing" },
+  { flag: "--filter-estimates-missing", aliases: ["--filter-estimate-missing"] },
+  { flag: "--filter-resolution-missing" },
+  { flag: "--filter-metadata-missing" },
+  { flag: "--filter-reviewer-missing" },
+  { flag: "--filter-risk-missing" },
+  { flag: "--filter-confidence-missing" },
+  { flag: "--filter-sprint-missing" },
+  { flag: "--filter-release-missing" },
+  { flag: "--has-notes" },
+  { flag: "--no-notes" },
+  { flag: "--has-learnings" },
+  { flag: "--no-learnings" },
+  { flag: "--has-files" },
+  { flag: "--no-files" },
+  { flag: "--has-docs" },
+  { flag: "--no-docs" },
+  { flag: "--has-tests" },
+  { flag: "--no-tests" },
+  { flag: "--has-comments" },
+  { flag: "--no-comments" },
+  { flag: "--has-deps" },
+  { flag: "--no-deps" },
+  { flag: "--has-body" },
+  { flag: "--empty-body" },
+  { flag: "--has-linked-command" },
+  { flag: "--no-linked-command" },
+  { flag: "--limit" },
+  { flag: "--offset" },
+  { flag: "--no-truncate", aliases: ["--all"] },
+  { flag: "--compact" },
+  { flag: "--brief" },
+  { flag: "--full" },
+  { flag: "--fields", list: true },
+  { flag: "--sort" },
+  { flag: "--order" },
+  { flag: "--tree" },
+  { flag: "--tree-depth" },
+  { flag: "--tree_depth" },
+  { flag: "--include-body" },
+  { flag: "--format" },
+  { flag: "--stream" }
 ];
-var TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS = [
-  { param: "parent", flag: "--parent" },
-  { param: "reviewer", flag: "--reviewer" },
-  { param: "risk", flag: "--risk" },
-  { param: "confidence", flag: "--confidence" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" },
-  { param: "blockedBy", flag: "--blocked-by" },
-  { param: "blockedReason", flag: "--blocked-reason" },
-  { param: "unblockNote", flag: "--unblock-note" },
-  { param: "reporter", flag: "--reporter" },
-  { param: "severity", flag: "--severity" },
-  { param: "environment", flag: "--environment" },
-  { param: "reproSteps", flag: "--repro-steps" },
-  { param: "resolution", flag: "--resolution" },
-  { param: "expectedResult", flag: "--expected-result" },
-  { param: "actualResult", flag: "--actual-result" },
-  { param: "affectedVersion", flag: "--affected-version" },
-  { param: "fixedVersion", flag: "--fixed-version" },
-  { param: "component", flag: "--component" },
-  { param: "regression", flag: "--regression", booleanish: true },
-  { param: "customerImpact", flag: "--customer-impact" },
-  { param: "definitionOfReady", flag: "--definition-of-ready", allowEmpty: true },
-  { param: "order", flag: "--order" },
-  { param: "goal", flag: "--goal" },
-  { param: "objective", flag: "--objective" },
-  { param: "value", flag: "--value" },
-  { param: "impact", flag: "--impact" },
-  { param: "outcome", flag: "--outcome" },
-  { param: "whyNow", flag: "--why-now" }
+var AGGREGATE_FLAG_CONTRACTS = [
+  { flag: "--group-by", list: true },
+  { flag: "--count" },
+  { flag: "--completion" },
+  { flag: "--sum" },
+  { flag: "--avg" },
+  { flag: "--include-unparented" },
+  { flag: "--include_unparented" },
+  { flag: "--status" },
+  { flag: "--type" },
+  { flag: "--tag" },
+  { flag: "--priority" },
+  { flag: "--deadline-before" },
+  { flag: "--deadline-after" },
+  { flag: "--assignee" },
+  { flag: "--assignee-filter" },
+  { flag: "--assignee_filter" },
+  { flag: "--parent" },
+  { flag: "--sprint" },
+  { flag: "--release" }
 ];
-var TOOL_CREATE_OPTION_CONTRACTS = [
-  { param: "title", flag: "--title" },
-  { param: "description", flag: "--description", allowEmpty: true },
-  { param: "type", flag: "--type" },
-  { param: "template", flag: "--template" },
-  { param: "createMode", flag: "--create-mode" },
-  { param: "schedulePreset", flag: "--schedule-preset" },
-  { param: "status", flag: "--status" },
-  { param: "priority", flag: "--priority" },
-  { param: "tags", flag: "--tags", allowEmpty: true },
-  { param: "addTags", flag: "--add-tags", repeatable: true },
-  { param: "body", flag: "--body", allowEmpty: true },
-  { param: "deadline", flag: "--deadline" },
-  { param: "estimate", flag: "--estimate" },
-  { param: "acceptanceCriteria", flag: "--acceptance-criteria", allowEmpty: true },
-  { param: "author", flag: "--author" },
-  { param: "message", flag: "--message", allowEmpty: true },
-  { param: "assignee", flag: "--assignee" },
-  { param: "allowMissingParent", flag: "--allow-missing-parent" },
-  { param: "reminder", flag: "--reminder", repeatable: true },
-  { param: "event", flag: "--event", repeatable: true },
-  { param: "typeOption", flag: "--type-option", repeatable: true },
-  { param: "field", flag: "--field", repeatable: true },
-  { param: "dep", flag: "--dep", repeatable: true },
-  { param: "comment", flag: "--comment", repeatable: true },
-  { param: "note", flag: "--note", repeatable: true },
-  { param: "learning", flag: "--learning", repeatable: true },
-  { param: "linkedFile", flag: "--file", repeatable: true },
-  { param: "linkedTest", flag: "--test", repeatable: true },
-  { param: "doc", flag: "--doc", repeatable: true },
-  { param: "unset", flag: "--unset", repeatable: true },
-  { param: "clearDeps", flag: "--clear-deps" },
-  { param: "clearComments", flag: "--clear-comments" },
-  { param: "clearNotes", flag: "--clear-notes" },
-  { param: "clearLearnings", flag: "--clear-learnings" },
-  { param: "clearFiles", flag: "--clear-files" },
-  { param: "clearTests", flag: "--clear-tests" },
-  { param: "clearDocs", flag: "--clear-docs" },
-  { param: "clearReminders", flag: "--clear-reminders" },
-  { param: "clearEvents", flag: "--clear-events" },
-  { param: "clearTypeOptions", flag: "--clear-type-options" }
+var DEDUPE_AUDIT_FLAG_CONTRACTS = [
+  { flag: "--mode" },
+  { flag: "--limit" },
+  { flag: "--threshold" },
+  { flag: "--status" },
+  { flag: "--type" },
+  { flag: "--tag" },
+  { flag: "--priority" },
+  { flag: "--deadline-before" },
+  { flag: "--deadline-after" },
+  { flag: "--assignee" },
+  { flag: "--assignee-filter" },
+  { flag: "--assignee_filter" },
+  { flag: "--parent" },
+  { flag: "--sprint" },
+  { flag: "--release" }
 ];
-var TOOL_UPDATE_OPTION_CONTRACTS = [
-  { param: "title", flag: "--title" },
-  { param: "description", flag: "--description", allowEmpty: true },
-  { param: "body", flag: "--body", allowEmpty: true },
-  { param: "status", flag: "--status" },
-  { param: "closeReason", flag: "--close-reason" },
-  { param: "priority", flag: "--priority" },
-  { param: "type", flag: "--type" },
-  { param: "tags", flag: "--tags", allowEmpty: true },
-  { param: "addTags", flag: "--add-tags", repeatable: true },
-  { param: "removeTags", flag: "--remove-tags", repeatable: true },
-  { param: "deadline", flag: "--deadline" },
-  { param: "estimate", flag: "--estimate" },
-  { param: "acceptanceCriteria", flag: "--acceptance-criteria", allowEmpty: true },
-  { param: "author", flag: "--author" },
-  { param: "message", flag: "--message", allowEmpty: true },
-  { param: "assignee", flag: "--assignee" },
-  { param: "dep", flag: "--dep", repeatable: true },
-  { param: "depRemove", flag: "--dep-remove", repeatable: true },
-  { param: "replaceDeps", flag: "--replace-deps" },
-  { param: "replaceTests", flag: "--replace-tests" },
-  { param: "comment", flag: "--comment", repeatable: true },
-  { param: "note", flag: "--note", repeatable: true },
-  { param: "learning", flag: "--learning", repeatable: true },
-  { param: "linkedFile", flag: "--file", repeatable: true },
-  { param: "linkedTest", flag: "--test", repeatable: true },
-  { param: "doc", flag: "--doc", repeatable: true },
-  { param: "reminder", flag: "--reminder", repeatable: true },
-  { param: "event", flag: "--event", repeatable: true },
-  { param: "typeOption", flag: "--type-option", repeatable: true },
-  { param: "field", flag: "--field", repeatable: true },
-  { param: "unset", flag: "--unset", repeatable: true },
-  { param: "clearDeps", flag: "--clear-deps" },
-  { param: "clearComments", flag: "--clear-comments" },
-  { param: "clearNotes", flag: "--clear-notes" },
-  { param: "clearLearnings", flag: "--clear-learnings" },
-  { param: "clearFiles", flag: "--clear-files" },
-  { param: "clearTests", flag: "--clear-tests" },
-  { param: "clearDocs", flag: "--clear-docs" },
-  { param: "clearReminders", flag: "--clear-reminders" },
-  { param: "clearEvents", flag: "--clear-events" },
-  { param: "clearTypeOptions", flag: "--clear-type-options" },
-  { param: "allowAuditUpdate", flag: "--allow-audit-update" },
-  { param: "allowAuditDepUpdate", flag: "--allow-audit-dep-update" }
+var DEDUPE_MERGE_FLAG_CONTRACTS = [
+  { flag: "--keep" },
+  { flag: "--close", list: true },
+  { flag: "--apply" },
+  { flag: "--dry-run" },
+  { flag: "--skip-children" },
+  { flag: "--author" },
+  { flag: "--message" }
 ];
-var TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS = [
-  { param: "filterStatus", flag: "--filter-status" },
-  { param: "filterType", flag: "--filter-type" },
-  { param: "filterTag", flag: "--filter-tag" },
-  { param: "filterPriority", flag: "--filter-priority" },
-  { param: "filterDeadlineBefore", flag: "--filter-deadline-before" },
-  { param: "filterDeadlineAfter", flag: "--filter-deadline-after" },
-  { param: "filterUpdatedAfter", flag: "--filter-updated-after" },
-  { param: "filterUpdatedBefore", flag: "--filter-updated-before" },
-  { param: "filterCreatedAfter", flag: "--filter-created-after" },
-  { param: "filterCreatedBefore", flag: "--filter-created-before" },
-  { param: "filterAssignee", flag: "--filter-assignee" },
-  { param: "filterAssigneeFilter", flag: "--filter-assignee-filter" },
-  { param: "filterParent", flag: "--filter-parent" },
-  { param: "filterSprint", flag: "--filter-sprint" },
-  { param: "filterRelease", flag: "--filter-release" },
-  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
-  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
-  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
-  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
-  { param: "filterReleaseMissing", flag: "--filter-release-missing" },
-  { param: "filterHasNotes", flag: "--filter-has-notes" },
-  { param: "filterNoNotes", flag: "--filter-no-notes" },
-  { param: "filterHasLearnings", flag: "--filter-has-learnings" },
-  { param: "filterNoLearnings", flag: "--filter-no-learnings" },
-  { param: "filterHasFiles", flag: "--filter-has-files" },
-  { param: "filterNoFiles", flag: "--filter-no-files" },
-  { param: "filterHasDocs", flag: "--filter-has-docs" },
-  { param: "filterNoDocs", flag: "--filter-no-docs" },
-  { param: "filterHasTests", flag: "--filter-has-tests" },
-  { param: "filterNoTests", flag: "--filter-no-tests" },
-  { param: "filterHasComments", flag: "--filter-has-comments" },
-  { param: "filterNoComments", flag: "--filter-no-comments" },
-  { param: "filterHasDeps", flag: "--filter-has-deps" },
-  { param: "filterNoDeps", flag: "--filter-no-deps" },
-  { param: "filterHasBody", flag: "--filter-has-body" },
-  { param: "filterEmptyBody", flag: "--filter-empty-body" },
-  { param: "filterHasLinkedCommand", flag: "--filter-has-linked-command" },
-  { param: "filterNoLinkedCommand", flag: "--filter-no-linked-command" },
-  { param: "ids", flag: "--ids" },
-  { param: "limit", flag: "--limit" },
-  { param: "offset", flag: "--offset" }
+var COMMENTS_AUDIT_FLAG_CONTRACTS = [
+  { flag: "--status" },
+  { flag: "--type" },
+  { flag: "--assignee" },
+  { flag: "--assignee-filter" },
+  { flag: "--assignee_filter" },
+  { flag: "--parent" },
+  { flag: "--tag" },
+  { flag: "--sprint" },
+  { flag: "--release" },
+  { flag: "--priority" },
+  { flag: "--limit-items" },
+  { flag: "--limit" },
+  { flag: "--full-history" },
+  { flag: "--latest" }
 ];
-var TOOL_NORMALIZE_FILTER_OPTION_CONTRACTS = [
-  { param: "filterStatus", flag: "--filter-status" },
-  { param: "filterType", flag: "--filter-type" },
-  { param: "filterTag", flag: "--filter-tag" },
-  { param: "filterPriority", flag: "--filter-priority" },
-  { param: "filterDeadlineBefore", flag: "--filter-deadline-before" },
-  { param: "filterDeadlineAfter", flag: "--filter-deadline-after" },
-  { param: "filterAssignee", flag: "--filter-assignee" },
-  { param: "filterAssigneeFilter", flag: "--filter-assignee-filter" },
-  { param: "filterParent", flag: "--filter-parent" },
-  { param: "filterSprint", flag: "--filter-sprint" },
-  { param: "filterRelease", flag: "--filter-release" },
-  { param: "limit", flag: "--limit" },
-  { param: "offset", flag: "--offset" }
+var COMMENTS_FLAG_CONTRACTS = [
+  { flag: "--add", aliases: ["--comment"] },
+  { flag: "--stdin" },
+  { flag: "--file" },
+  { flag: "--edit" },
+  { flag: "--delete" },
+  { flag: "--limit" },
+  { flag: "--author" },
+  { flag: "--message" },
+  { flag: "--allow-audit-comment" },
+  { flag: "--force" }
 ];
-var TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS = [
-  { param: "filterStatus", flag: "--filter-status" },
-  { param: "filterType", flag: "--filter-type" },
-  { param: "filterTag", flag: "--filter-tag" },
-  { param: "filterPriority", flag: "--filter-priority" },
-  { param: "filterDeadlineBefore", flag: "--filter-deadline-before" },
-  { param: "filterDeadlineAfter", flag: "--filter-deadline-after" },
-  { param: "filterUpdatedAfter", flag: "--filter-updated-after" },
-  { param: "filterUpdatedBefore", flag: "--filter-updated-before" },
-  { param: "filterCreatedAfter", flag: "--filter-created-after" },
-  { param: "filterCreatedBefore", flag: "--filter-created-before" },
-  { param: "filterAssignee", flag: "--filter-assignee" },
-  { param: "filterAssigneeFilter", flag: "--filter-assignee-filter" },
-  { param: "filterParent", flag: "--filter-parent" },
-  { param: "filterSprint", flag: "--filter-sprint" },
-  { param: "filterRelease", flag: "--filter-release" },
-  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
-  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
-  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
-  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
-  { param: "filterReleaseMissing", flag: "--filter-release-missing" },
-  { param: "filterHasNotes", flag: "--filter-has-notes" },
-  { param: "filterNoNotes", flag: "--filter-no-notes" },
-  { param: "filterHasLearnings", flag: "--filter-has-learnings" },
-  { param: "filterNoLearnings", flag: "--filter-no-learnings" },
-  { param: "filterHasFiles", flag: "--filter-has-files" },
-  { param: "filterNoFiles", flag: "--filter-no-files" },
-  { param: "filterHasDocs", flag: "--filter-has-docs" },
-  { param: "filterNoDocs", flag: "--filter-no-docs" },
-  { param: "filterHasTests", flag: "--filter-has-tests" },
-  { param: "filterNoTests", flag: "--filter-no-tests" },
-  { param: "filterHasComments", flag: "--filter-has-comments" },
-  { param: "filterNoComments", flag: "--filter-no-comments" },
-  { param: "filterHasDeps", flag: "--filter-has-deps" },
-  { param: "filterNoDeps", flag: "--filter-no-deps" },
-  { param: "filterHasBody", flag: "--filter-has-body" },
-  { param: "filterEmptyBody", flag: "--filter-empty-body" },
-  { param: "filterHasLinkedCommand", flag: "--filter-has-linked-command" },
-  { param: "filterNoLinkedCommand", flag: "--filter-no-linked-command" },
-  { param: "ids", flag: "--ids" },
-  { param: "limit", flag: "--limit" },
-  { param: "offset", flag: "--offset" }
+var NOTES_FLAG_CONTRACTS = [
+  { flag: "--add", aliases: ["--note"] },
+  { flag: "--limit" },
+  { flag: "--author" },
+  { flag: "--message" },
+  { flag: "--allow-audit-note" },
+  { flag: "--allow-audit-comment" },
+  { flag: "--force" }
 ];
-var TOOL_ACTIVITY_OPTION_CONTRACTS = [
-  { param: "id", flag: "--id" },
-  { param: "op", flag: "--op" },
-  { param: "author", flag: "--author" },
-  { param: "from", flag: "--from" },
-  { param: "to", flag: "--to" },
-  { param: "limit", flag: "--limit" },
-  { param: "compact", flag: "--compact" },
-  { param: "full", flag: "--full" }
+var LEARNINGS_FLAG_CONTRACTS = [
+  { flag: "--add", aliases: ["--learning"] },
+  { flag: "--limit" },
+  { flag: "--author" },
+  { flag: "--message" },
+  { flag: "--allow-audit-learning" },
+  { flag: "--allow-audit-comment" },
+  { flag: "--force" }
 ];
-var TOOL_CONTEXT_OPTION_CONTRACTS = [
-  { param: "date", flag: "--date" },
-  { param: "from", flag: "--from" },
-  { param: "to", flag: "--to" },
-  { param: "type", flag: "--type" },
-  { param: "tag", flag: "--tag" },
-  { param: "priority", flag: "--priority" },
-  { param: "assignee", flag: "--assignee" },
-  { param: "assigneeFilter", flag: "--assignee-filter" },
-  { param: "sprint", flag: "--sprint" },
-  { param: "release", flag: "--release" },
-  { param: "parent", flag: "--parent" },
-  { param: "limit", flag: "--limit" },
-  { param: "format", flag: "--format" },
-  { param: "depth", flag: "--depth" },
-  { param: "fields", flag: "--fields" },
-  { param: "section", flag: "--section", repeatable: true },
-  { param: "activityLimit", flag: "--activity-limit" },
-  { param: "staleThreshold", flag: "--stale-threshold" }
+var FILES_FLAG_CONTRACTS = [
+  { flag: "--add" },
+  { flag: "--add-glob" },
+  { flag: "--remove" },
+  { flag: "--migrate" },
+  // GH-170 (pm-pfnx): single-value note applied to every --add/--add-glob link
+  // in the invocation (embedded note= wins; usage error without an add).
+  { flag: "--note" },
+  { flag: "--list" },
+  { flag: "--append-stable" },
+  { flag: "--validate-paths" },
+  { flag: "--audit" },
+  { flag: "--author" },
+  { flag: "--message" },
+  { flag: "--force" }
 ];
-
-// dist/sdk/cli-contracts/tool-parameter-tables.js
-var PM_TOOL_PARAMETER_PROPERTIES = {
-  json: { type: "boolean", default: true },
-  quiet: { type: "boolean" },
-  profile: { type: "boolean" },
-  noExtensions: { type: "boolean" },
-  noPager: { type: "boolean" },
-  path: { type: "string" },
-  pmExecutable: { type: "string" },
-  timeoutMs: { type: "number" },
-  id: { type: "string" },
-  target: { type: "string" },
-  github: { type: "string" },
-  ref: { type: "string" },
-  query: { type: "string" },
-  keywords: { type: "string" },
-  fields: { type: "string" },
-  sort: { type: "string", enum: ["priority", "deadline", "updated_at", "created_at", "title", "parent"] },
-  prefix: { type: "string" },
-  preset: { type: "string", enum: ["minimal", "default", "strict", "custom"] },
-  typePreset: { type: "string", enum: ["agile", "ops", "research"] },
-  defaults: { type: "boolean" },
-  verbose: { type: "boolean" },
-  agentGuidance: { type: "string", enum: ["ask", "add", "skip", "status"] },
-  withPackages: { type: "boolean" },
-  scope: { type: "string", enum: ["project", "global"] },
-  allOver: { type: "number" },
-  minEntries: { type: "number" },
-  closed: { type: "boolean" },
-  allStreams: { type: "boolean" },
-  contractAction: { type: "string" },
-  command: { type: "string" },
-  schemaOnly: { type: "boolean" },
-  flagsOnly: { type: "boolean" },
-  availabilityOnly: { type: "boolean" },
-  runtimeOnly: { type: "boolean" },
-  activeOnly: { type: "boolean" },
-  eagerTags: { type: "boolean" },
-  fullChangedFields: { type: "boolean" },
-  idOnly: { type: "boolean" },
-  allowMissingParent: { type: "boolean" },
-  duplicateOf: { type: "string" },
-  configAction: { type: "string", enum: ["get", "set", "list", "export"] },
-  key: { type: "string" },
-  title: { type: "string" },
-  description: { type: "string" },
-  type: { type: "string" },
-  template: { type: "string" },
-  createMode: { type: "string", enum: ["strict", "progressive"] },
-  schedulePreset: { type: "string", enum: ["lightweight"] },
-  status: { type: "string" },
-  filterStatus: { type: "string" },
-  filterType: { type: "string" },
-  filterTag: { type: "string" },
-  filterPriority: { anyOf: [{ type: "string" }, { type: "number" }] },
-  filterDeadlineBefore: { type: "string" },
-  filterDeadlineAfter: { type: "string" },
-  filterUpdatedAfter: { type: "string" },
-  filterUpdatedBefore: { type: "string" },
-  filterCreatedAfter: { type: "string" },
-  filterCreatedBefore: { type: "string" },
-  filterAssignee: { type: "string" },
-  filterAssigneeFilter: { type: "string", enum: ["assigned", "unassigned"] },
-  filterParent: { type: "string" },
-  filterSprint: { type: "string" },
-  filterRelease: { type: "string" },
-  closeReason: { type: "string" },
-  reason: { type: "string" },
-  priority: { anyOf: [{ type: "string" }, { type: "number" }] },
-  tags: { type: "string" },
-  addTags: { type: "array", items: { type: "string" } },
-  removeTags: { type: "array", items: { type: "string" } },
-  body: { type: "string" },
-  deadline: { type: "string" },
-  estimate: { anyOf: [{ type: "string" }, { type: "number" }] },
-  acceptanceCriteria: { type: "string" },
-  author: { type: "string" },
-  message: { type: "string" },
-  assignee: { type: "string" },
-  assigneeFilter: { type: "string", enum: ["assigned", "unassigned"] },
-  parent: { type: "string" },
-  reviewer: { type: "string" },
-  risk: { type: "string" },
-  confidence: { anyOf: [{ type: "string" }, { type: "number" }] },
-  sprint: { type: "string" },
-  release: { type: "string" },
-  blockedBy: { type: "string" },
-  blockedReason: { type: "string" },
-  unblockNote: { type: "string" },
-  reporter: { type: "string" },
-  severity: { type: "string" },
-  environment: { type: "string" },
-  reproSteps: { type: "string" },
-  resolution: { type: "string" },
-  expectedResult: { type: "string" },
-  actualResult: { type: "string" },
-  affectedVersion: { type: "string" },
-  fixedVersion: { type: "string" },
-  component: { type: "string" },
-  regression: { anyOf: [{ type: "boolean" }, { type: "string" }, { type: "number" }] },
-  customerImpact: { type: "string" },
-  definitionOfReady: { type: "string" },
-  order: { anyOf: [{ type: "string" }, { type: "number" }] },
-  goal: { type: "string" },
-  objective: { type: "string" },
-  value: { type: "string" },
-  impact: { type: "string" },
-  outcome: { type: "string" },
-  whyNow: { type: "string" },
-  mode: {
-    type: "string",
-    enum: ["keyword", "semantic", "hybrid", "title_exact", "title_fuzzy", "parent_scope"]
-  },
-  semanticWeight: { anyOf: [{ type: "string" }, { type: "number" }] },
-  op: { type: "string" },
-  compact: { type: "boolean" },
-  brief: { type: "boolean" },
-  full: { type: "boolean" },
-  view: { type: "string", enum: ["agenda", "day", "week", "month"] },
-  date: { type: "string" },
-  from: { type: "string" },
-  before: { type: "string" },
-  to: { type: "string" },
-  past: { type: "boolean" },
-  fullPeriod: { type: "boolean" },
-  include: { type: "string" },
-  recurrenceLookaheadDays: { anyOf: [{ type: "string" }, { type: "number" }] },
-  recurrenceLookbackDays: { anyOf: [{ type: "string" }, { type: "number" }] },
-  occurrenceLimit: { anyOf: [{ type: "string" }, { type: "number" }] },
-  includeLinked: { type: "boolean" },
-  semantic: { type: "boolean" },
-  hybrid: { type: "boolean" },
-  titleExact: { type: "boolean" },
-  phraseExact: { type: "boolean" },
-  highlight: { type: "boolean" },
-  includeBody: { type: "boolean" },
-  noTruncate: { type: "boolean" },
-  tag: { type: "string" },
-  deadlineBefore: { type: "string" },
-  deadlineAfter: { type: "string" },
-  updatedAfter: { type: "string" },
-  updatedBefore: { type: "string" },
-  createdAfter: { type: "string" },
-  createdBefore: { type: "string" },
-  filterAcMissing: { type: "boolean" },
-  filterEstimatesMissing: { type: "boolean" },
-  filterResolutionMissing: { type: "boolean" },
-  filterMetadataMissing: { type: "boolean" },
-  filterReviewerMissing: { type: "boolean" },
-  filterRiskMissing: { type: "boolean" },
-  filterConfidenceMissing: { type: "boolean" },
-  filterSprintMissing: { type: "boolean" },
-  filterReleaseMissing: { type: "boolean" },
-  // Content-field presence/absence filters (list/search). The --no-* variants
-  // select items where the field is empty/absent.
-  hasNotes: { type: "boolean" },
-  noNotes: { type: "boolean" },
-  hasLearnings: { type: "boolean" },
-  noLearnings: { type: "boolean" },
-  hasFiles: { type: "boolean" },
-  noFiles: { type: "boolean" },
-  hasDocs: { type: "boolean" },
-  noDocs: { type: "boolean" },
-  hasTests: { type: "boolean" },
-  noTests: { type: "boolean" },
-  hasComments: { type: "boolean" },
-  noComments: { type: "boolean" },
-  hasDeps: { type: "boolean" },
-  noDeps: { type: "boolean" },
-  hasBody: { type: "boolean" },
-  emptyBody: { type: "boolean" },
-  hasLinkedCommand: { type: "boolean" },
-  noLinkedCommand: { type: "boolean" },
-  // Bulk-selection (update-many/close-many) content + governance filters mirror
-  // the list/search presence filters under the --filter- prefix.
-  filterHasNotes: { type: "boolean" },
-  filterNoNotes: { type: "boolean" },
-  filterHasLearnings: { type: "boolean" },
-  filterNoLearnings: { type: "boolean" },
-  filterHasFiles: { type: "boolean" },
-  filterNoFiles: { type: "boolean" },
-  filterHasDocs: { type: "boolean" },
-  filterNoDocs: { type: "boolean" },
-  filterHasTests: { type: "boolean" },
-  filterNoTests: { type: "boolean" },
-  filterHasComments: { type: "boolean" },
-  filterNoComments: { type: "boolean" },
-  filterHasDeps: { type: "boolean" },
-  filterNoDeps: { type: "boolean" },
-  filterHasBody: { type: "boolean" },
-  filterEmptyBody: { type: "boolean" },
-  filterHasLinkedCommand: { type: "boolean" },
-  filterNoLinkedCommand: { type: "boolean" },
-  ids: { type: "string" },
-  limit: { anyOf: [{ type: "string" }, { type: "number" }] },
-  limitItems: { anyOf: [{ type: "string" }, { type: "number" }] },
-  fullHistory: { type: "boolean" },
-  latest: { anyOf: [{ type: "string" }, { type: "number" }] },
-  offset: { anyOf: [{ type: "string" }, { type: "number" }] },
-  progress: { type: "boolean" },
-  background: { type: "boolean" },
-  runId: { type: "string" },
-  stream: {
-    anyOf: [{ type: "boolean" }, { type: "string", enum: ["stdout", "stderr", "both", "rows", "ndjson", "jsonl"] }]
-  },
-  tail: { anyOf: [{ type: "string" }, { type: "number" }] },
-  addJson: { type: "array", items: { type: "string" } },
-  match: { type: "string" },
-  onlyIndex: { anyOf: [{ type: "string" }, { type: "number" }] },
-  onlyLast: { type: "boolean" },
-  envSet: { type: "array", items: { type: "string" } },
-  envClear: { type: "array", items: { type: "string" } },
-  sharedHostSafe: { type: "boolean" },
-  detail: { type: "string", enum: ["summary", "deep"] },
-  trace: { type: "boolean" },
-  reload: { type: "boolean" },
-  watch: { type: "boolean" },
-  runtimeProbe: { type: "boolean" },
-  fixManagedState: { type: "boolean" },
-  pmContext: { type: "string", enum: ["schema", "tracker", "auto"] },
-  overrideLinkedPmContext: { type: "boolean" },
-  failOnContextMismatch: { type: "boolean" },
-  failOnSkipped: { type: "boolean" },
-  failOnEmptyTestRun: { type: "boolean" },
-  requireAssertionsForPm: { type: "boolean" },
-  checkContext: { type: "boolean" },
-  autoPmContext: { type: "boolean" },
-  diff: { type: "boolean" },
-  storage: { type: "boolean" },
-  metadataCoverage: { type: "boolean" },
-  fieldUtilization: { type: "boolean" },
-  byAssignee: { type: "boolean" },
-  byTag: { type: "boolean" },
-  byPriority: { type: "boolean" },
-  tagPrefix: { type: "string" },
-  verify: { type: "boolean" },
-  literal: { type: "array", items: { type: "string" } },
-  regex: { type: "array", items: { type: "string" } },
-  replacement: { type: "string" },
-  timeout: { anyOf: [{ type: "string" }, { type: "number" }] },
-  validateClose: { type: "string", enum: ["off", "warn", "strict"] },
-  checkMetadata: { type: "boolean" },
-  metadataProfile: { type: "string", enum: ["core", "strict", "custom"] },
-  checkResolution: { type: "boolean" },
-  checkLifecycle: { type: "boolean" },
-  checkStaleBlockers: { type: "boolean" },
-  dependencyCycleSeverity: { type: "string", enum: ["off", "warn", "error"] },
-  checkFiles: { type: "boolean" },
-  strictDirectories: { type: "boolean" },
-  checkOnly: { type: "boolean" },
-  checkTelemetry: { type: "boolean" },
-  noRefresh: { type: "boolean" },
-  refreshVectors: { type: "boolean" },
-  verboseStaleItems: { type: "boolean" },
-  skipVectors: { type: "boolean" },
-  skipIntegrity: { type: "boolean" },
-  skipDrift: { type: "boolean" },
-  verboseDiagnostics: { type: "boolean" },
-  allAffectedIds: { type: "boolean" },
-  scanMode: { type: "string", enum: ["default", "tracked-all", "tracked-all-strict"] },
-  includePmInternals: { type: "boolean" },
-  verboseFileLists: { type: "boolean" },
-  strictExit: { type: "boolean" },
-  failOnWarn: { type: "boolean" },
-  fixHints: { type: "boolean" },
-  autoFix: { type: "boolean" },
-  fixScope: { type: "array", items: { type: "string", enum: ["metadata", "resolution", "estimates", "lifecycle"] } },
-  pruneMissing: { type: "boolean" },
-  checkHistoryDrift: { type: "boolean" },
-  checkCommandReferences: { type: "boolean" },
-  allowAuditNote: { type: "boolean" },
-  allowAuditLearning: { type: "boolean" },
-  allowAuditComment: { type: "boolean" },
-  edit: { type: "integer", minimum: 1 },
-  delete: { type: "integer", minimum: 1 },
-  allowAuditUpdate: { type: "boolean" },
-  allowAuditDepUpdate: { type: "boolean" },
-  allowAuditRelease: { type: "boolean" },
-  dryRun: { type: "boolean" },
-  all: { type: "boolean" },
-  clear: { type: "boolean" },
-  cliOnly: { type: "boolean" },
-  packagesOnly: { type: "boolean" },
-  repair: { type: "boolean" },
-  packageName: { type: "string" },
-  rollback: { type: "string" },
-  noCheckpoint: { type: "boolean" },
-  force: { type: "boolean" },
-  run: { type: "boolean" },
-  count: { type: "boolean" },
-  sum: { type: "string" },
-  avg: { type: "string" },
-  tree: { type: "boolean" },
-  treeDepth: { anyOf: [{ type: "string" }, { type: "number" }] },
-  includeUnparented: { type: "boolean" },
-  gcScope: {
-    type: "array",
-    items: { type: "string", enum: ["index", "embeddings", "runtime", "locks"] }
-  },
-  maxDepth: { anyOf: [{ type: "string" }, { type: "number" }] },
-  collapse: { type: "string", enum: ["none", "repeated"] },
-  summary: { type: "boolean" },
-  shell: { type: "string", enum: ["bash", "zsh", "fish"] },
-  stdin: { type: "boolean" },
-  file: { type: "string" },
-  preserveSourceIds: { type: "boolean" },
-  folder: { type: "string" },
-  subcommand: { type: "string" },
-  name: { type: "string" },
-  defaultStatus: { type: "string" },
-  alias: { type: "array", items: { type: "string" } },
-  role: { type: "array", items: { type: "string" } },
-  fieldType: { type: "string", enum: ["string", "number", "boolean", "string_array"] },
-  commands: { type: "array", items: { type: "string" } },
-  cliFlag: { type: "string" },
-  required: { type: "boolean" },
-  requiredOnCreate: { type: "boolean" },
-  allowUnset: { type: "boolean" },
-  requiredTypes: { type: "array", items: { type: "string" } },
-  infer: { type: "boolean" },
-  minCount: { type: "number" },
-  text: { type: "string" },
-  add: { type: "array", items: { type: "string" } },
-  addGlob: { type: "array", items: { type: "string" } },
-  remove: { type: "array", items: { type: "string" } },
-  migrate: { type: "array", items: { type: "string" } },
-  discover: { type: "boolean" },
-  apply: { type: "boolean" },
-  discoveryNote: { type: "string" },
-  // GH-170 (pm-pfnx): single-string note for files/docs add batches (the shared
-  // `note` key below is the array-typed create/update note seed).
-  addNote: { type: "string" },
-  list: { type: "boolean" },
-  appendStable: { type: "boolean" },
-  validatePaths: { type: "boolean" },
-  audit: { type: "boolean" },
-  dep: { type: "array", items: { type: "string" } },
-  depRemove: { type: "array", items: { type: "string" } },
-  replaceDeps: { type: "boolean" },
-  replaceTests: { type: "boolean" },
-  comment: { type: "array", items: { type: "string" } },
-  note: { type: "array", items: { type: "string" } },
-  learning: { type: "array", items: { type: "string" } },
-  linkedFile: { type: "array", items: { type: "string" } },
-  linkedTest: { type: "array", items: { type: "string" } },
-  doc: { type: "array", items: { type: "string" } },
-  reminder: { type: "array", items: { type: "string" } },
-  event: { type: "array", items: { type: "string" } },
-  typeOption: { type: "array", items: { type: "string" } },
-  field: { type: "array", items: { type: "string" } },
-  unset: { type: "array", items: { type: "string" } },
-  clearDeps: { type: "boolean" },
-  clearComments: { type: "boolean" },
-  clearNotes: { type: "boolean" },
-  clearLearnings: { type: "boolean" },
-  clearFiles: { type: "boolean" },
-  clearTests: { type: "boolean" },
-  clearDocs: { type: "boolean" },
-  clearReminders: { type: "boolean" },
-  clearEvents: { type: "boolean" },
-  clearTypeOptions: { type: "boolean" },
-  criterion: { type: "array", items: { type: "string" } },
-  clearCriteria: { type: "boolean" },
-  groupBy: { type: "string" },
-  completion: { type: "boolean" },
-  threshold: { anyOf: [{ type: "string" }, { type: "number" }] },
-  format: { type: "string" },
-  depth: { type: "string", enum: ["brief", "standard", "deep", "full"] },
-  section: { type: "array", items: { type: "string", enum: ["hierarchy", "activity", "progress", "blockers", "files", "workload", "staleness", "tests"] } },
-  activityLimit: { anyOf: [{ type: "string" }, { type: "number" }] },
-  staleThreshold: { type: "string" },
-  policy: { type: "string" }
-};
-var PLAN_SUBCOMMAND_VALUES = [
-  "create",
-  "show",
-  "add-step",
-  "update-step",
-  "complete-step",
-  "block-step",
-  "reorder-step",
-  "remove-step",
-  "link",
-  "unlink",
-  "decision",
-  "discovery",
-  "validation",
-  "resume",
-  "approve",
-  "materialize"
-];
-var PLAN_ACTION_PARAMETER_PROPERTIES = {
-  subcommand: { type: "string", enum: [...PLAN_SUBCOMMAND_VALUES] },
-  stepRef: { type: "string" },
-  reorderTo: { anyOf: [{ type: "string" }, { type: "number" }] },
-  scope: { type: "string" },
-  harness: { type: "string", enum: [...PLAN_HARNESS_VALUES] },
-  mode: { type: "string", enum: [...PLAN_MODE_VALUES] },
-  resumeContext: { type: "string" },
-  related: { type: "string" },
-  blocks: { type: "string" },
-  claim: { type: "boolean" },
-  fromSearch: { type: "string" },
-  stepTitle: { type: "string" },
-  // pm-6mit: ordered step titles for create (string or array; values are never
-  // comma-split). On step subcommands a single value aliases stepTitle.
-  step: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
-  stepBody: { type: "string" },
-  stepOwner: { type: "string" },
-  stepStatus: { type: "string", enum: [...PLAN_STEP_STATUS_VALUES] },
-  stepEvidence: { type: "string" },
-  stepBlockedReason: { type: "string" },
-  stepReplacement: { type: "string" },
-  dependsOn: { type: "string" },
-  link: { type: "string" },
-  linkKind: { type: "string", enum: [...PLAN_STEP_LINK_KIND_VALUES] },
-  linkNote: { type: "string" },
-  promoteToItemDep: { type: "boolean" },
-  allowMultipleActive: { type: "boolean" },
-  file: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
-  test: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
-  doc: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
-  decisionText: { type: "string" },
-  decision: { type: "string" },
-  decisionRationale: { type: "string" },
-  decisionEvidence: { type: "string" },
-  discoveryText: { type: "string" },
-  discovery: { type: "string" },
-  validationText: { type: "string" },
-  validation: { type: "string" },
-  validationCommand: { type: "string" },
-  validationExpected: { type: "string" },
-  steps: { type: "array", items: { type: "string" } },
-  materializeType: { type: "string" },
-  materializeParent: { type: "string" },
-  materializeTags: { type: "string" }
-};
-var PLAN_ACTION_PARAMETER_METADATA = {
-  subcommand: {
-    description: "Plan workflow operation to run.",
-    examples: ["create", "show", "add-step", "approve"]
-  },
-  stepRef: {
-    description: "Plan step id or order for step lifecycle subcommands.",
-    examples: ["plan-step-001", "1"]
-  },
-  reorderTo: {
-    description: "New integer order for reorder-step.",
-    examples: [1, "2"]
-  },
-  scope: {
-    description: "Short free-text scope statement describing what the Plan covers.",
-    examples: ["Release readiness audit", "Search package migration"]
-  },
-  mode: {
-    description: "Plan lifecycle mode.",
-    examples: ["draft", "research", "approved"]
-  },
-  step: {
-    description: "Ordered initial step titles for create (string or array, never comma-split; stepTitle, when also set, becomes the first step). For step subcommands a single value aliases stepTitle.",
-    examples: [["Read the code", "Write the fix", "Run the tests"]]
-  },
-  file: {
-    description: "File link to attach while creating or materializing a Plan.",
-    examples: ["path=src/cli.ts,note=implementation surface"]
-  },
-  test: {
-    description: "Test command link to attach while creating or materializing a Plan.",
-    examples: ["command=pnpm build,timeout_seconds=300"]
-  },
-  doc: {
-    description: "Documentation link to attach while creating or materializing a Plan.",
-    examples: ["path=docs/SDK.md,note=public API reference"]
-  }
-};
-var PM_TOOL_PARAMETER_METADATA = {
-  action: {
-    description: "Tool action to execute."
-  },
-  path: {
-    description: "Optional PM data root override for this invocation.",
-    examples: [".agents/pm"]
-  },
-  scope: {
-    description: "Scope selector for commands that operate on project or global state. Linked files, docs, and tests default to project scope when omitted.",
-    examples: ["project", "global"]
-  },
-  detail: {
-    description: "Detail mode for commands that support concise and deep diagnostics.",
-    examples: ["summary", "deep"]
-  },
-  trace: {
-    description: "When true for extension-doctor, include actionable registration traces in deep diagnostics."
-  },
-  reload: {
-    description: "When true for extension action payloads, trigger cache-busted extension module reload."
-  },
-  watch: {
-    description: "When true for extension-reload/extension action payloads, enable watch mode semantics."
-  },
-  runtimeProbe: {
-    description: "When true for extension-manage, run a doctor-like runtime activation probe for parity fields."
-  },
-  fixManagedState: {
-    description: "When true for extension-manage/extension-doctor, adopt unmanaged extensions before diagnostics/update checks."
-  },
-  target: {
-    description: "Positional target argument for the selected action (ID, source, package source, or extension name).",
-    examples: ["pm-a1b2", ".agents/pm/extensions/sample", "sample-extension"]
-  },
-  github: {
-    description: "GitHub shorthand owner/repo[/path] source for package/extension install actions.",
-    examples: ["org/repo/extensions/sample"]
-  },
-  ref: {
-    description: "Git ref/branch/tag used when installing from GitHub shorthand/URL sources.",
-    examples: ["main", "v1.0.0"]
-  },
-  cliOnly: {
-    description: "Restrict upgrade to the pm CLI/SDK npm package."
-  },
-  packagesOnly: {
-    description: "Restrict upgrade to managed installable pm packages."
-  },
-  repair: {
-    description: "Force npm global reinstall semantics when upgrading the pm CLI/SDK."
-  },
-  tag: {
-    description: "npm version or dist-tag used for CLI and registry package upgrades.",
-    examples: ["latest", "next", "2026.5.11"]
-  },
-  packageName: {
-    description: "Override the pm CLI package name for self-upgrade automation and tests.",
-    examples: ["@unbrained/pm-cli"]
-  },
-  json: {
-    description: "Emit machine-readable JSON output."
-  },
-  quiet: {
-    description: "Suppress stdout payload output."
-  },
-  noExtensions: {
-    description: "Disable extension loading for this invocation."
-  },
-  noPager: {
-    description: "Disable pager integration for help and long output."
-  },
-  profile: {
-    description: "Emit deterministic timing diagnostics to stderr."
-  },
-  timeoutMs: {
-    description: "Tool execution timeout in milliseconds.",
-    examples: [12e4]
-  },
-  id: {
-    description: "Item identifier for read or mutation actions.",
-    examples: ["pm-a1b2"]
-  },
-  runId: {
-    description: "Background test run identifier.",
-    examples: ["tr-kq9x3f-93acde"]
-  },
-  title: {
-    description: "Item title text."
-  },
-  description: {
-    description: "Item description text."
-  },
-  type: {
-    description: "Item type name from the active runtime type registry.",
-    examples: ["Task", "Feature"]
-  },
-  subcommand: {
-    description: "Subcommand selector for schema and telemetry actions."
-  },
-  name: {
-    description: "Custom item type name (schema add-type/remove-type/show), custom status id (schema show-status/add-status/remove-status), or custom field key (schema add-field/remove-field/show-field).",
-    examples: ["Spike", "review", "component"]
-  },
-  defaultStatus: {
-    description: "Default status hint recorded for a custom item type.",
-    examples: ["open"]
-  },
-  alias: {
-    description: "Aliases for the custom item type or status (repeatable).",
-    examples: [["spike", "research"]]
-  },
-  role: {
-    description: "Lifecycle roles for a custom status (schema add-status): draft, active, blocked, terminal, terminal_done, terminal_canceled, default_open, default_close, default_cancel.",
-    examples: [["active"], ["terminal", "terminal_done"]]
-  },
-  fieldType: {
-    description: "Value type for a custom field (schema add-field): string, number, boolean, or string_array.",
-    examples: ["string", "number", "string_array"]
-  },
-  commands: {
-    description: "Commands a custom field is wired onto (schema add-field): create, update, update_many, list, search, calendar, context.",
-    examples: [["create", "update"], ["create", "update", "list"]]
-  },
-  cliFlag: {
-    description: "Override the auto-derived CLI flag for a custom field (schema add-field).",
-    examples: ["--owner"]
-  },
-  required: {
-    description: "Mark a custom field as always required (schema add-field)."
-  },
-  requiredOnCreate: {
-    description: "Mark a custom field as required at create time (schema add-field)."
-  },
-  allowUnset: {
-    description: "Whether a custom field may be cleared via --unset (schema add-field); defaults to true."
-  },
-  requiredTypes: {
-    description: "Restrict a custom field's requirement to specific item types (schema add-field).",
-    examples: [["Bug"], ["Story", "Spike"]]
-  },
-  infer: {
-    description: "Infer custom item types from title-prefix conventions (schema add-type); previews unless apply is true."
-  },
-  minCount: {
-    description: "Minimum number of items sharing a title prefix for schema add-type inference (default 10).",
-    examples: [10, 25]
-  },
-  preset: {
-    description: "Governance preset for initialization flows.",
-    examples: ["minimal", "default", "strict"]
-  },
-  typePreset: {
-    description: "Domain item-type preset registered during initialization.",
-    examples: ["agile", "ops", "research"]
-  },
-  defaults: {
-    description: "Use non-interactive setup defaults during initialization."
-  },
-  verbose: {
-    description: "Include the full resolved settings tree in init output."
-  },
-  agentGuidance: {
-    description: "Control AGENTS.md/CLAUDE.md guidance behavior during init: ask, add, skip, or status.",
-    examples: ["ask", "add", "skip", "status"]
-  },
-  withPackages: {
-    description: "Install all bundled first-party pm packages during initialization."
-  },
-  createMode: {
-    description: "Create required-option policy mode.",
-    examples: ["strict", "progressive"]
-  },
-  schedulePreset: {
-    description: "Schedule-centric create preset for Reminder, Meeting, and Event types.",
-    examples: ["lightweight"]
-  },
-  status: {
-    description: "Item status value. Statuses are project-configurable via .agents/pm/settings.json (schema block); the built-in defaults are draft, open, in_progress, blocked, closed, canceled. Custom statuses defined for the project are accepted \u2014 discover the active set with the pm_contracts tool (workspace.statuses) or `pm contracts`. Unknown statuses are rejected at runtime with a did-you-mean hint rather than blocked by a fixed schema enum.",
-    examples: ["open", "in_progress"]
-  },
-  priority: {
-    description: "Priority value in range 0..4.",
-    examples: [0, 1, "2"]
-  },
-  order: {
-    description: "Planning order/rank value for create/update, or sort direction (asc|desc) for list-family sorting.",
-    examples: [0, 1, "2", "asc", "desc"]
-  },
-  sort: {
-    description: "List-family sort field selector.",
-    examples: ["priority", "deadline", "updated_at", "created_at", "title", "parent"]
-  },
-  tags: {
-    description: "Comma-delimited tag list.",
-    examples: ["pm-cli,agent-ux"]
-  },
-  addTags: {
-    description: "Tags to add to the existing list without replacing it. Each entry may be CSV or a JSON array.",
-    examples: [["agent-ux"], ["fix", "security"]]
-  },
-  removeTags: {
-    description: "Tags to remove from the existing list. Each entry may be CSV or a JSON array.",
-    examples: [["stale"], ["legacy", "wontfix"]]
-  },
-  deadline: {
-    description: "ISO/date timestamp or relative offset (+6h/+1d/+2w/+6m).",
-    examples: ["2026-04-01T00:00:00.000Z", "+1d"]
-  },
-  reminder: {
-    description: "Repeatable reminder seed entries at=<iso|relative>,text=<text>.",
-    examples: [["at=+2d,text=Review PR"]]
-  },
-  event: {
-    description: "Repeatable event seed entries start=<iso|relative> with end=<iso|relative> or duration=<relative|30min|PT30M>. Bare `m` remains months for backward compatibility.",
-    examples: [
-      ["start=2026-07-01T10:00:00Z,duration=2h,title=planning"],
-      ["start=2026-07-01T10:00:00Z,duration=30min,title=standup"],
-      ["start=2026-07-01T10:00:00Z,duration=PT30M,title=window"]
-    ]
-  },
-  estimate: {
-    description: "Estimated effort in minutes.",
-    examples: [60, "120"]
-  },
-  acceptanceCriteria: {
-    description: "Acceptance criteria text."
-  },
-  author: {
-    description: "Mutation author identity.",
-    examples: ["codex-agent"]
-  },
-  message: {
-    description: "History message for mutation audit trail."
-  },
-  assignee: {
-    description: "Assignee identity.",
-    examples: ["codex-agent"]
-  },
-  assigneeFilter: {
-    description: "Assignee presence selector for list/calendar/context/comments-audit filters.",
-    examples: ["assigned", "unassigned"]
-  },
-  parent: {
-    description: "Parent item ID filter for hierarchical list queries.",
-    examples: ["pm-epic01"]
-  },
-  unset: {
-    description: "Repeatable list of front-matter fields to clear explicitly during create/update mutations.",
-    examples: [["deadline", "assignee"], ["close-reason"]]
-  },
-  clearDeps: {
-    description: "When true, clear linked dependencies."
-  },
-  replaceDeps: {
-    description: "When true for update, atomically replace dependencies with the supplied --dep values."
-  },
-  replaceTests: {
-    description: "When true for update, atomically replace linked tests with the supplied --test values."
-  },
-  clearComments: {
-    description: "When true, clear item comments."
-  },
-  clearNotes: {
-    description: "When true, clear item notes."
-  },
-  clearLearnings: {
-    description: "When true, clear item learnings."
-  },
-  clearFiles: {
-    description: "When true, clear linked files."
-  },
-  clearTests: {
-    description: "When true, clear linked tests."
-  },
-  clearDocs: {
-    description: "When true, clear linked docs."
-  },
-  clearReminders: {
-    description: "When true, clear reminders."
-  },
-  clearEvents: {
-    description: "When true, clear events."
-  },
-  clearTypeOptions: {
-    description: "When true, clear type option metadata."
-  },
-  clearCriteria: {
-    description: "When true for config set criteria-list keys (definition-of-done, metadata-required-fields, lifecycle pattern lists), clear the criteria list."
-  },
-  mode: {
-    description: "Mode selector for search/reindex (keyword|semantic|hybrid) and dedupe-audit (title_exact|title_fuzzy|parent_scope).",
-    examples: ["keyword", "hybrid", "title_exact"]
-  },
-  semanticWeight: {
-    description: "Per-query hybrid semantic weight override in [0,1] for search action; invalid values fall back to settings.",
-    examples: [0.2, "0.7"]
-  },
-  op: {
-    description: "History operation filter for activity output.",
-    examples: ["create", "update", "close", "update_audit"]
-  },
-  fullPeriod: {
-    description: "For day/week/month calendar views, include the full anchored period instead of clipping the start to now."
-  },
-  progress: {
-    description: "Emit progress diagnostics to stderr for long-running operations."
-  },
-  background: {
-    description: "Run linked tests in managed background mode."
-  },
-  addJson: {
-    description: "Repeatable JSON object or array input for adding linked-test entries without CSV escaping loss.",
-    examples: [[`{"command":"node scripts/run-tests.mjs test -- tests/unit/output.spec.ts","timeout_seconds":240}`]]
-  },
-  match: {
-    description: "Run only linked tests whose command or path contains this case-insensitive substring.",
-    examples: ["output.spec.ts", "coverage"]
-  },
-  onlyIndex: {
-    description: "Run only the 1-based linked-test index from pm test <id> --list order.",
-    examples: [1, "2"]
-  },
-  onlyLast: {
-    description: "Run only the most recently added linked-test entry."
-  },
-  envSet: {
-    description: "Repeatable runtime environment KEY=VALUE overrides for linked-test execution.",
-    examples: [["PORT=0", "PLAYWRIGHT_HTML_OPEN=never"]]
-  },
-  envClear: {
-    description: "Repeatable runtime environment variable names to clear before linked-test execution.",
-    examples: [["PLAYWRIGHT_BASE_URL"]]
-  },
-  sharedHostSafe: {
-    description: "Apply additive shared-host-safe runtime defaults during linked-test execution."
-  },
-  pmContext: {
-    description: "PM linked-test context mode (schema keeps isolated tracker data; tracker seeds source tracker data; auto uses tracker for PM tracker-read linked commands).",
-    examples: ["schema", "tracker", "auto"]
-  },
-  overrideLinkedPmContext: {
-    description: "Force run-level --pm-context to override per-linked-test pm_context_mode metadata for all linked-test entries."
-  },
-  failOnContextMismatch: {
-    description: "Fail linked PM command runs when source and sandbox tracker item counts differ."
-  },
-  failOnSkipped: {
-    description: "Treat skipped linked tests as dependency-failed policy violations."
-  },
-  failOnEmptyTestRun: {
-    description: "Treat successful linked-test commands that report zero executed tests as failures."
-  },
-  requireAssertionsForPm: {
-    description: "Require assertion metadata for linked PM command test entries during run execution."
-  },
-  checkContext: {
-    description: "Run linked PM command context preflight diagnostics before command execution."
-  },
-  autoPmContext: {
-    description: "Auto-remediate PM tracker-read linked commands by routing those entries through tracker context regardless of linked-test pm_context_mode overrides."
-  },
-  dryRun: {
-    description: "Preview command effects without mutating storage artifacts."
-  },
-  all: {
-    description: "For history-repair action: scan every stream for drift and repair each drifted stream in one audited pass (mutually exclusive with id)."
-  },
-  clear: {
-    description: "For focus action: clear the session focused item instead of setting it (mutually exclusive with id)."
-  },
-  gcScope: {
-    description: "Repeatable gc scope selector values (index, embeddings, runtime, locks, checkpoints).",
-    examples: [["index", "embeddings"], ["runtime"], ["locks"], ["checkpoints"]]
-  },
-  storage: {
-    description: "For stats action: include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries) for compaction and storage planning."
-  },
-  fieldUtilization: {
-    description: "For stats action: include a field_utilization block reporting present/total/percent for content fields (notes, learnings, files, docs, tests, comments, deps, body, linked_command) across all items so under-documented dimensions are visible at a glance."
-  },
-  offset: {
-    description: "Number of matching rows to skip before limit is applied.",
-    examples: [0, 50, "100"]
-  },
-  before: {
-    description: "For history-compact, compact entries strictly before this boundary (version number or ISO timestamp). Single-id mode only.",
-    examples: ["5", "2026-06-01T00:00:00.000Z"]
-  },
-  allOver: {
-    description: "For history-compact bulk mode, compact every stream with more than N entries. When history.compact_policy is enabled and this is omitted, the policy's max_entries is used.",
-    examples: [200, "500"]
-  },
-  minEntries: {
-    description: "For history-compact bulk mode, skip streams with at most N entries as already-compact (default 3).",
-    examples: [3, "10"]
-  },
-  closed: {
-    description: "For history-compact bulk mode, compact only closed (terminal) items' history streams."
-  },
-  allStreams: {
-    description: "For history-compact bulk mode, compact every history stream regardless of lifecycle state."
-  },
-  limitItems: {
-    description: "Maximum number of filtered items to include in comments-audit output (alias: --limit).",
-    examples: [10, "25"]
-  },
-  fullHistory: {
-    description: "When true for comments-audit, export full per-item comment history rows; cannot be combined with latest."
-  },
-  latest: {
-    description: "Number of most recent comments to include per item in comments-audit output (use 0 for summary-only item rows).",
-    examples: [0, 1, "3"]
-  },
-  literal: {
-    description: "Repeatable literal matcher used by history-redact to scrub exact string values.",
-    examples: ["[redacted_path_prefix]/private/path"]
-  },
-  regex: {
-    description: "Repeatable regex matcher used by history-redact. Accepts either /pattern/flags or a raw pattern (global mode is auto-enabled).",
-    examples: ["/192\\\\.168\\\\.[0-9.]+/g", "token=[A-Za-z0-9_-]+"]
-  },
-  replacement: {
-    description: 'Replacement text used by history-redact (defaults to "[redacted]").',
-    examples: ["[scrubbed_path]"]
-  },
-  validateClose: {
-    description: 'Close-time metadata validation mode ("off", "warn", or "strict").',
-    examples: ["off", "warn", "strict"]
-  },
-  checkMetadata: {
-    description: "Run metadata completeness checks."
-  },
-  metadataProfile: {
-    description: "Select metadata validation profile for --check-metadata.",
-    examples: ["core", "strict", "custom"]
-  },
-  checkResolution: {
-    description: "Run closed-item resolution metadata checks."
-  },
-  checkLifecycle: {
-    description: "Run active-item lifecycle governance drift checks."
-  },
-  checkStaleBlockers: {
-    description: "Include stale blocker-pattern diagnostics in lifecycle checks."
-  },
-  dependencyCycleSeverity: {
-    description: "Set dependency-cycle warning policy for lifecycle checks.",
-    examples: ["off", "warn", "error"]
-  },
-  checkFiles: {
-    description: "Run linked-file and orphaned-file checks."
-  },
-  strictDirectories: {
-    description: "Treat optional item-type directories as required health failures."
-  },
-  checkOnly: {
-    description: "For health action, run read-only diagnostics without refreshing vectors."
-  },
-  checkTelemetry: {
-    description: "For health action, probe telemetry endpoint health and include network diagnostics."
-  },
-  noRefresh: {
-    description: "For health action, skip vector refresh while still running checks."
-  },
-  refreshVectors: {
-    description: "For health action, explicitly refresh stale vectors."
-  },
-  verboseStaleItems: {
-    description: "For health action, include full stale-item arrays in vectorization details."
-  },
-  skipVectors: {
-    description: "For health action, skip vectorization checks for a faster diagnostic run."
-  },
-  skipIntegrity: {
-    description: "For health action, skip item/history file integrity checks for a faster diagnostic run."
-  },
-  skipDrift: {
-    description: "For health action, skip history drift hash checks for a faster diagnostic run."
-  },
-  scanMode: {
-    description: "Select file candidate scan mode for --check-files.",
-    examples: ["default", "tracked-all", "tracked-all-strict"]
-  },
-  includePmInternals: {
-    description: "Include PM storage internals in tracked-all candidate scans."
-  },
-  verboseFileLists: {
-    description: "For validate action, include full file-path lists for --check-files details."
-  },
-  verboseDiagnostics: {
-    description: "For validate action, include full diagnostic ID lists instead of compact summaries."
-  },
-  strictExit: {
-    description: "Return non-zero exit when health/validate/extension-doctor warnings are present."
-  },
-  failOnWarn: {
-    description: "Alias for strictExit in health/validate/extension-doctor action payloads."
-  },
-  fixHints: {
-    description: "For validate action, add a machine-executable fix_hints[] of pm commands to each failing check's details."
-  },
-  autoFix: {
-    description: "For validate action, apply the safe, deterministic subset of fix-hint remediations (field backfills) automatically; combine with dryRun to preview and fixScope to grant gated scopes."
-  },
-  fixScope: {
-    description: "For validate action, grant --auto-fix scopes (metadata, resolution, estimates, lifecycle). Defaults to the safe scopes metadata and resolution; estimates (per-type default estimated_minutes backfill) and lifecycle must be named explicitly.",
-    examples: [["estimates"], ["lifecycle"], ["metadata", "resolution"]]
-  },
-  pruneMissing: {
-    description: "For validate action, remove stale linked-file/doc LINKS whose paths classified as deleted (link removal only \u2014 never touches real files); honors dryRun."
-  },
-  checkHistoryDrift: {
-    description: "Run item/history hash drift checks."
-  },
-  checkCommandReferences: {
-    description: "Run linked-command PM-ID reference checks."
-  },
-  allowAuditNote: {
-    description: "For notes action, allow non-owner append-only note audits without requiring --force."
-  },
-  allowAuditLearning: {
-    description: "For learnings action, allow non-owner append-only learning audits without requiring --force."
-  },
-  allowAuditComment: {
-    description: "For comments action, allow non-owner append-only comment audits without requiring --force."
-  },
-  edit: {
-    description: "For comments action, replace the comment at this 1-based index with the supplied replacement text (add/stdin/file)."
-  },
-  delete: {
-    description: "For comments action, delete the comment at this 1-based index."
-  },
-  stdin: {
-    description: "When true for comments action, read comment text from piped stdin (supports multiline markdown)."
-  },
-  file: {
-    description: "Path to input file for actions that read payload text, such as comments --file.",
-    examples: ["notes/comment.md"]
-  },
-  allowAuditUpdate: {
-    description: "Allow non-owner metadata-only update audits without requiring --force."
-  },
-  allowAuditDepUpdate: {
-    description: "Allow non-owner append-only dependency update audits without requiring --force."
-  },
-  allowAuditRelease: {
-    description: "Allow non-owner release handoffs that clear assignee metadata without requiring --force."
-  },
-  preserveSourceIds: {
-    description: "Preserve explicit source IDs during Beads imports instead of normalizing to tracker prefix.",
-    examples: [true]
-  },
-  appendStable: {
-    description: "When true for files action, preserve existing linked-file order and append new links without full-array resorting."
-  },
-  discover: {
-    description: "When true for files action, use `pm files discover <id>` to scan item text for referenced file paths."
-  },
-  apply: {
-    description: "Persist changes instead of returning a dry-run preview: for files discovery, add the missing discovered file links; for schema add-type --infer, register the inferred custom item types."
-  },
-  discoveryNote: {
-    description: "Note attached to file links added by files discovery.",
-    examples: ["discovered from item text"]
-  },
-  addNote: {
-    description: "Note attached to every link added by add/addGlob in this call (per-entry embedded note= wins; requires add or addGlob). Maps to the CLI --note flag on pm files/pm docs.",
-    examples: ["command wiring"]
-  },
-  list: {
-    description: "When true for files/docs action, list the current linked paths without mutating them.",
-    examples: [true]
-  },
-  stream: {
-    description: "Stream selector: test-runs logs accepts stdout|stderr|both; activity accepts boolean/rows|ndjson|jsonl for line-delimited output.",
-    examples: ["stderr", "stdout", "both", "rows", "ndjson", "jsonl", true]
-  },
-  tail: {
-    description: "Number of lines to tail for background run logs.",
-    examples: [100]
-  },
-  query: {
-    description: "Search query text for search action."
-  },
-  keywords: {
-    description: "Alias for query in search action payloads."
-  },
-  includeLinked: {
-    description: "Include readable linked docs/files/tests content in keyword and hybrid lexical scoring."
-  },
-  titleExact: {
-    description: "For search action, require exact normalized title match for the full query string."
-  },
-  phraseExact: {
-    description: "For search action, require exact normalized query phrase match in item text fields."
-  },
-  highlight: {
-    description: "For search action, emit per-field matched-text snippets (wrapped in \xAB\u2026\xBB) on each hit. Off by default."
-  },
-  includeBody: {
-    description: "When true for list-family actions, include item body text in projected rows."
-  },
-  noTruncate: {
-    description: "When true for list-family actions, return every matched row, overriding any limit (surfaces total when rows were dropped)."
-  },
-  compact: {
-    description: "Render compact projection output for search and list-family actions."
-  },
-  full: {
-    description: "Enable command-specific full/detail output mode when supported, such as deep item reads for get or full payload mode for search/history."
-  },
-  fields: {
-    description: "Comma-separated projection fields for get, search, list-family, or context outputs. Valid field names are command-specific (e.g. score/matched_fields apply to search; context projects focus-row fields such as priority/deadline/completion_pct).",
-    examples: ["id,title,status,parent,type", "id,title,score,matched_fields", "id,title,priority,deadline"]
-  },
-  groupBy: {
-    description: "Comma-separated aggregate grouping fields (supported: parent,type,priority,status,assignee,tags,sprint,release).",
-    examples: ["parent,type", "type,status", "priority,assignee", "tags", "sprint,release"]
-  },
-  count: {
-    description: "Enable grouped count output for aggregate action."
-  },
-  completion: {
-    description: "For aggregate action, add open/in_progress/closed/other counts and completion_pct per group."
-  },
-  sum: {
-    description: "Numeric field to sum per aggregate group (count and null_count are still returned).",
-    examples: ["estimated_minutes", "priority"]
-  },
-  avg: {
-    description: "Numeric field to average per aggregate group (count and null_count are still returned).",
-    examples: ["estimated_minutes", "priority"]
-  },
-  tree: {
-    description: "When true for list/get actions, render recursive parent/child tree ordering."
-  },
-  treeDepth: {
-    description: "Maximum recursion depth for tree output (0 keeps root rows only).",
-    examples: [0, 1, "2"]
-  },
-  includeUnparented: {
-    description: "Include unparented rows when aggregate grouping includes parent."
-  },
-  maxDepth: {
-    description: "Maximum dependency traversal depth for deps action (0 keeps only the root node).",
-    examples: [0, 1, "2"]
-  },
-  collapse: {
-    description: 'Dependency tree collapse mode for deps action ("none" or "repeated").',
-    examples: ["none", "repeated"]
-  },
-  summary: {
-    description: "When true for deps action, return counts only without full tree/graph payloads."
-  },
-  threshold: {
-    description: "Dedupe-audit fuzzy title similarity threshold between 0 and 1.",
-    examples: [0.5, "0.75"]
-  },
-  shell: {
-    description: "Shell target for completion generation.",
-    examples: ["bash"]
-  },
-  eagerTags: {
-    description: "When true for completion, eagerly embed current tracker tags into generated scripts (legacy mode)."
-  },
-  contractAction: {
-    description: "Filter contracts schema to one tool action.",
-    examples: ["create", "update"]
-  },
-  command: {
-    description: "Scope contracts output to one CLI command name; action/schema surfaces narrow by default.",
-    examples: ["create", "search", "list"]
-  },
-  schemaOnly: {
-    description: "When true, contracts action returns schema-focused payloads (mutually exclusive with flagsOnly/availabilityOnly)."
-  },
-  flagsOnly: {
-    description: "When true, contracts action returns only command flag surface payloads (mutually exclusive projection mode)."
-  },
-  availabilityOnly: {
-    description: "When true, contracts action returns only action availability payloads (mutually exclusive projection mode)."
-  },
-  runtimeOnly: {
-    description: "When true, contracts action only includes actions invocable in the current runtime."
-  },
-  activeOnly: {
-    description: "Alias for runtimeOnly in contracts action payloads."
-  },
-  depth: {
-    description: "Context depth level controlling how many sections are included (brief=focus+agenda, standard=+hierarchy/activity/progress/workload, deep=all sections, full=every section with no per-section row cap).",
-    examples: ["brief", "standard", "deep", "full"]
-  },
-  section: {
-    description: "Repeatable section selector for context; overrides --depth when provided.",
-    examples: [["hierarchy", "activity"], ["blockers", "files", "staleness"]]
-  },
-  activityLimit: {
-    description: "Maximum number of recent activity entries to include in context output.",
-    examples: [5, 10, "20"]
-  },
-  staleThreshold: {
-    description: "Staleness cutoff in days for context staleness section (e.g. 7 or 7d).",
-    examples: ["7", "14d", "30"]
-  }
-};
-
-// dist/sdk/cli-contracts.js
-function normalizeUniqueStringList(values) {
-  return [...new Set(Array.from(values).filter((value) => value.trim().length > 0))];
-}
-function normalizeFlagAliasKey(flag) {
-  if (!flag.startsWith("--")) {
-    return flag;
-  }
-  return `--${flag.slice(2).replaceAll("_", "-")}`;
-}
-function withFlagAliasMetadata(flagContracts) {
-  const aliasesByCanonical = /* @__PURE__ */ new Map();
-  for (const contract of flagContracts) {
-    const canonical = normalizeFlagAliasKey(contract.flag);
-    const bucket = aliasesByCanonical.get(canonical) ?? /* @__PURE__ */ new Set();
-    if (contract.flag !== canonical) {
-      bucket.add(contract.flag);
-    }
-    for (const alias of contract.aliases ?? []) {
-      if (alias !== canonical) {
-        bucket.add(alias);
-      }
-    }
-    aliasesByCanonical.set(canonical, bucket);
-  }
-  return flagContracts.map((contract) => {
-    const canonical = normalizeFlagAliasKey(contract.flag);
-    if (contract.flag !== canonical) {
-      return contract;
-    }
-    const aliases = normalizeUniqueStringList([
-      ...contract.aliases ?? [],
-      ...aliasesByCanonical.get(canonical)
-    ]).filter((alias) => alias !== canonical);
-    if (aliases.length === 0) {
-      return contract;
-    }
-    return {
-      ...contract,
-      aliases
-    };
-  });
-}
-function compactFlagAliasContracts(flagContracts) {
-  const withAliases = withFlagAliasMetadata(flagContracts);
-  const canonicalFlags = new Set(withAliases.map((contract) => contract.flag));
-  return withAliases.filter((contract) => {
-    const canonical = normalizeFlagAliasKey(contract.flag);
-    return contract.flag === canonical || !canonicalFlags.has(canonical);
-  });
-}
-var SUBCOMMAND_GLOBAL_FLAG_CONTRACTS = [
-  { flag: "--json" },
-  { flag: "--quiet" },
-  { flag: "--no-changed-fields" },
-  { flag: "--id-only" },
-  { flag: "--pm-path", aliases: ["--path"] },
-  { flag: "--no-extensions" },
-  { flag: "--no-pager" },
-  { flag: "--profile" },
-  { flag: "--help" }
-];
-var GLOBAL_FLAG_CONTRACTS = [
-  ...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS,
-  { flag: "--version" }
-];
-var LIST_FILTER_FLAG_CONTRACTS = [
-  { flag: "--status", list: true },
-  { flag: "--type" },
-  { flag: "--tag", aliases: ["--tags"] },
-  { 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" },
-  { flag: "--parent" },
-  { flag: "--sprint" },
-  { flag: "--release" },
-  { flag: "--filter-ac-missing" },
-  { flag: "--filter-estimates-missing", aliases: ["--filter-estimate-missing"] },
-  { flag: "--filter-resolution-missing" },
-  { flag: "--filter-metadata-missing" },
-  { flag: "--filter-reviewer-missing" },
-  { flag: "--filter-risk-missing" },
-  { flag: "--filter-confidence-missing" },
-  { flag: "--filter-sprint-missing" },
-  { flag: "--filter-release-missing" },
-  { flag: "--has-notes" },
-  { flag: "--no-notes" },
-  { flag: "--has-learnings" },
-  { flag: "--no-learnings" },
-  { flag: "--has-files" },
-  { flag: "--no-files" },
-  { flag: "--has-docs" },
-  { flag: "--no-docs" },
-  { flag: "--has-tests" },
-  { flag: "--no-tests" },
-  { flag: "--has-comments" },
-  { flag: "--no-comments" },
-  { flag: "--has-deps" },
-  { flag: "--no-deps" },
-  { flag: "--has-body" },
-  { flag: "--empty-body" },
-  { flag: "--has-linked-command" },
-  { flag: "--no-linked-command" },
-  { flag: "--limit" },
-  { flag: "--offset" },
-  { flag: "--no-truncate", aliases: ["--all"] },
-  { flag: "--compact" },
-  { flag: "--brief" },
-  { flag: "--full" },
-  { flag: "--fields", list: true },
-  { flag: "--sort" },
-  { flag: "--order" },
-  { flag: "--tree" },
-  { flag: "--tree-depth" },
-  { flag: "--tree_depth" },
-  { flag: "--include-body" },
-  { flag: "--format" },
-  { flag: "--stream" }
-];
-var AGGREGATE_FLAG_CONTRACTS = [
-  { flag: "--group-by", list: true },
-  { flag: "--count" },
-  { flag: "--completion" },
-  { flag: "--sum" },
-  { flag: "--avg" },
-  { flag: "--include-unparented" },
-  { flag: "--include_unparented" },
-  { flag: "--status" },
-  { flag: "--type" },
-  { flag: "--tag" },
-  { flag: "--priority" },
-  { flag: "--deadline-before" },
-  { flag: "--deadline-after" },
-  { flag: "--assignee" },
-  { flag: "--assignee-filter" },
-  { flag: "--assignee_filter" },
-  { flag: "--parent" },
-  { flag: "--sprint" },
-  { flag: "--release" }
-];
-var DEDUPE_AUDIT_FLAG_CONTRACTS = [
-  { flag: "--mode" },
-  { flag: "--limit" },
-  { flag: "--threshold" },
-  { flag: "--status" },
-  { flag: "--type" },
-  { flag: "--tag" },
-  { flag: "--priority" },
-  { flag: "--deadline-before" },
-  { flag: "--deadline-after" },
-  { flag: "--assignee" },
-  { flag: "--assignee-filter" },
-  { flag: "--assignee_filter" },
-  { flag: "--parent" },
-  { flag: "--sprint" },
-  { flag: "--release" }
-];
-var DEDUPE_MERGE_FLAG_CONTRACTS = [
-  { flag: "--keep" },
-  { flag: "--close", list: true },
-  { flag: "--apply" },
-  { flag: "--dry-run" },
-  { flag: "--skip-children" },
-  { flag: "--author" },
-  { flag: "--message" }
-];
-var COMMENTS_AUDIT_FLAG_CONTRACTS = [
-  { flag: "--status" },
-  { flag: "--type" },
-  { flag: "--assignee" },
-  { flag: "--assignee-filter" },
-  { flag: "--assignee_filter" },
-  { flag: "--parent" },
-  { flag: "--tag" },
-  { flag: "--sprint" },
-  { flag: "--release" },
-  { flag: "--priority" },
-  { flag: "--limit-items" },
-  { flag: "--limit" },
-  { flag: "--full-history" },
-  { flag: "--latest" }
-];
-var COMMENTS_FLAG_CONTRACTS = [
-  { flag: "--add", aliases: ["--comment"] },
-  { flag: "--stdin" },
-  { flag: "--file" },
-  { flag: "--edit" },
-  { flag: "--delete" },
-  { flag: "--limit" },
-  { flag: "--author" },
-  { flag: "--message" },
-  { flag: "--allow-audit-comment" },
-  { flag: "--force" }
-];
-var NOTES_FLAG_CONTRACTS = [
-  { flag: "--add", aliases: ["--note"] },
-  { flag: "--limit" },
-  { flag: "--author" },
-  { flag: "--message" },
-  { flag: "--allow-audit-note" },
-  { flag: "--allow-audit-comment" },
-  { flag: "--force" }
-];
-var LEARNINGS_FLAG_CONTRACTS = [
-  { flag: "--add", aliases: ["--learning"] },
-  { flag: "--limit" },
-  { flag: "--author" },
-  { flag: "--message" },
-  { flag: "--allow-audit-learning" },
-  { flag: "--allow-audit-comment" },
-  { flag: "--force" }
-];
-var FILES_FLAG_CONTRACTS = [
-  { flag: "--add" },
-  { flag: "--add-glob" },
-  { flag: "--remove" },
-  { flag: "--migrate" },
-  // GH-170 (pm-pfnx): single-value note applied to every --add/--add-glob link
-  // in the invocation (embedded note= wins; usage error without an add).
-  { flag: "--note" },
-  { flag: "--list" },
-  { flag: "--append-stable" },
-  { flag: "--validate-paths" },
-  { flag: "--audit" },
-  { flag: "--author" },
-  { flag: "--message" },
-  { flag: "--force" }
-];
-var DOCS_FLAG_CONTRACTS = [
-  { flag: "--add" },
-  { flag: "--add-glob" },
-  { flag: "--remove" },
-  { flag: "--migrate" },
-  // GH-170 (pm-pfnx): see FILES_FLAG_CONTRACTS --note.
-  { flag: "--note" },
-  { flag: "--list" },
-  { flag: "--validate-paths" },
-  { flag: "--audit" },
-  { flag: "--author" },
-  { flag: "--message" },
-  { flag: "--force" }
+var DOCS_FLAG_CONTRACTS = [
+  { flag: "--add" },
+  { flag: "--add-glob" },
+  { flag: "--remove" },
+  { flag: "--migrate" },
+  // GH-170 (pm-pfnx): see FILES_FLAG_CONTRACTS --note.
+  { flag: "--note" },
+  { flag: "--list" },
+  { flag: "--validate-paths" },
+  { flag: "--audit" },
+  { flag: "--author" },
+  { flag: "--message" },
+  { flag: "--force" }
 ];
 var HISTORY_FLAG_CONTRACTS = [
   { flag: "--limit" },
@@ -2689,6 +1146,11 @@ var SCHEMA_FLAG_CONTRACTS = [
   { flag: "--author" },
   { flag: "--force" }
 ];
+var PROFILE_FLAG_CONTRACTS = [
+  { flag: "--dry-run" },
+  { flag: "--author" },
+  { flag: "--force" }
+];
 var PLAN_FLAG_CONTRACTS = [
   { flag: "--title" },
   { flag: "--description" },
@@ -2781,6 +1243,8 @@ var EXTENSION_FLAG_CONTRACTS = [
   { flag: "--list" },
   { flag: "--manage" },
   { flag: "--describe" },
+  { flag: "--markdown" },
+  { flag: "--output" },
   { flag: "--reload" },
   { flag: "--watch" },
   { flag: "--doctor" },
@@ -2811,6 +1275,8 @@ var EXTENSION_INIT_FLAG_CONTRACTS = [
   ...EXTENSION_SCOPE_FLAG_CONTRACTS,
   { flag: "--capability" }
 ];
+var PACKAGE_FLAG_CONTRACTS = [...EXTENSION_FLAG_CONTRACTS, { flag: "--declarative" }];
+var PACKAGE_INIT_FLAG_CONTRACTS = [...EXTENSION_INIT_FLAG_CONTRACTS, { flag: "--declarative" }];
 var EXTENSION_INSTALL_FLAG_CONTRACTS = [
   { flag: "--project" },
   { flag: "--local" },
@@ -2821,7 +1287,11 @@ var EXTENSION_INSTALL_FLAG_CONTRACTS = [
 ];
 var EXTENSION_UNINSTALL_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
 var EXTENSION_EXPLORE_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
-var EXTENSION_DESCRIBE_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
+var EXTENSION_DESCRIBE_FLAG_CONTRACTS = [
+  ...EXTENSION_SCOPE_FLAG_CONTRACTS,
+  { flag: "--markdown" },
+  { flag: "--output" }
+];
 var EXTENSION_ADOPT_ALL_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
 var EXTENSION_ACTIVATE_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
 var EXTENSION_DEACTIVATE_FLAG_CONTRACTS = EXTENSION_SCOPE_FLAG_CONTRACTS;
@@ -3545,308 +2015,1797 @@ var CONTEXT_FLAG_CONTRACTS = [
   { flag: "--release" },
   { flag: "--parent" },
   { flag: "--limit" },
-  { flag: "--format" },
-  { flag: "--depth" },
+  { flag: "--format" },
+  { flag: "--depth" },
+  { flag: "--fields", list: true },
+  { flag: "--section" },
+  { flag: "--activity-limit" },
+  { flag: "--stale-threshold" }
+];
+var GET_FLAG_CONTRACTS = [
+  { flag: "--depth" },
+  { flag: "--full" },
+  { flag: "--fields", list: true },
+  { flag: "--tree" },
+  { flag: "--tree-depth" },
+  { flag: "--tree_depth" },
+  { flag: "--format" }
+];
+var GUIDE_FLAG_CONTRACTS = [
+  { flag: "--list" },
+  { flag: "--format" },
+  { flag: "--depth" }
+];
+var DEPS_FLAG_CONTRACTS = [
+  { flag: "--format" },
+  { flag: "--max-depth" },
+  { flag: "--collapse" },
+  { flag: "--summary" }
+];
+var EVAL_FLAG_CONTRACTS = [
+  { flag: "--mode" },
+  { flag: "--k" },
+  { flag: "--fail-under" },
+  { flag: "--queries" },
+  { flag: "--format" }
+];
+var NEXT_FLAG_CONTRACTS = [
+  { flag: "--type" },
+  { flag: "--tag" },
+  { flag: "--priority" },
+  { flag: "--assignee" },
+  { flag: "--assignee-filter" },
+  { flag: "--assignee_filter" },
+  { flag: "--sprint" },
+  { flag: "--release" },
+  { flag: "--parent" },
+  { flag: "--limit" },
+  { flag: "--blocked-limit" },
+  { flag: "--blocked_limit" },
+  { flag: "--ready-only" },
+  { flag: "--ready_only" },
+  { flag: "--format" }
+];
+var SEARCH_FLAG_CONTRACTS = [
+  { flag: "--mode" },
+  { flag: "--semantic" },
+  { flag: "--hybrid" },
+  { flag: "--match-mode" },
+  { flag: "--min-score" },
+  { flag: "--count" },
+  { flag: "--semantic-weight" },
+  { flag: "--include-linked" },
+  { flag: "--title-exact" },
+  { flag: "--phrase-exact" },
+  { flag: "--highlight" },
+  { flag: "--compact" },
+  { flag: "--full" },
   { flag: "--fields", list: true },
-  { flag: "--section" },
-  { flag: "--activity-limit" },
-  { flag: "--stale-threshold" }
+  { flag: "--format" },
+  { flag: "--limit" },
+  { flag: "--status", list: true },
+  { flag: "--type" },
+  { flag: "--tag", aliases: ["--tags"] },
+  { flag: "--priority" },
+  { flag: "--deadline-before" },
+  { flag: "--deadline-after" },
+  { flag: "--updated-after" },
+  { flag: "--updated-before" },
+  { flag: "--created-after" },
+  { flag: "--created-before" },
+  { flag: "--assignee" },
+  { flag: "--sprint" },
+  { flag: "--release" },
+  { flag: "--parent" },
+  { flag: "--filter-reviewer-missing" },
+  { flag: "--filter-risk-missing" },
+  { flag: "--filter-confidence-missing" },
+  { flag: "--filter-sprint-missing" },
+  { flag: "--filter-release-missing" },
+  { flag: "--has-notes" },
+  { flag: "--no-notes" },
+  { flag: "--has-learnings" },
+  { flag: "--no-learnings" },
+  { flag: "--has-files" },
+  { flag: "--no-files" },
+  { flag: "--has-docs" },
+  { flag: "--no-docs" },
+  { flag: "--has-tests" },
+  { flag: "--no-tests" },
+  { flag: "--has-comments" },
+  { flag: "--no-comments" },
+  { flag: "--has-deps" },
+  { flag: "--no-deps" },
+  { flag: "--has-body" },
+  { flag: "--empty-body" },
+  { flag: "--has-linked-command" },
+  { flag: "--no-linked-command" }
+];
+var CONTRACTS_FLAG_CONTRACTS = [
+  { flag: "--action" },
+  { flag: "--command" },
+  { flag: "--schema-only" },
+  { flag: "--flags-only" },
+  { flag: "--availability-only" },
+  { flag: "--runtime-only" },
+  { flag: "--active-only" },
+  { flag: "--full" }
+];
+var COMPLETION_FLAG_CONTRACTS = [
+  { flag: "--eager-tags" }
+];
+function toUniqueFlagContracts(contracts) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const contract of contracts) {
+    const aliasKey = (contract.aliases ?? []).join(",");
+    const key = `${contract.flag}|${contract.short ?? ""}|${aliasKey}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    unique.push(contract);
+  }
+  return unique;
+}
+function withSubcommandGlobalFlags(contracts) {
+  return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
+}
+var LIST_COMMAND_FLAG_ALIASES = [
+  "list",
+  "list-all",
+  "list-draft",
+  "list-open",
+  "list-in-progress",
+  "list-blocked",
+  "list-closed",
+  "list-canceled"
+];
+var SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
+  ...LIST_COMMAND_FLAG_ALIASES.map((command) => [command, LIST_FILTER_FLAG_CONTRACTS]),
+  ["templates", CREATE_FLAG_CONTRACTS],
+  ["cal", CALENDAR_FLAG_CONTRACTS],
+  ["ctx", CONTEXT_FLAG_CONTRACTS],
+  ["test-runs-worker", TEST_RUNS_FLAG_CONTRACTS],
+  ["init", INIT_FLAG_CONTRACTS],
+  ["config", CONFIG_FLAG_CONTRACTS],
+  ["extension", EXTENSION_FLAG_CONTRACTS],
+  // `--declarative` is package-only (see PACKAGE_FLAG_CONTRACTS).
+  ["package", PACKAGE_FLAG_CONTRACTS],
+  ["packages", PACKAGE_FLAG_CONTRACTS],
+  ["install", INSTALL_FLAG_CONTRACTS],
+  ["upgrade", UPGRADE_FLAG_CONTRACTS],
+  ["create", CREATE_FLAG_CONTRACTS],
+  ["copy", COPY_FLAG_CONTRACTS],
+  ["focus", FOCUS_FLAG_CONTRACTS],
+  ["aggregate", AGGREGATE_FLAG_CONTRACTS],
+  ["dedupe-audit", DEDUPE_AUDIT_FLAG_CONTRACTS],
+  ["dedupe-merge", DEDUPE_MERGE_FLAG_CONTRACTS],
+  ["normalize", NORMALIZE_FLAG_CONTRACTS],
+  ["calendar", CALENDAR_FLAG_CONTRACTS],
+  ["context", CONTEXT_FLAG_CONTRACTS],
+  ["get", GET_FLAG_CONTRACTS],
+  ["guide", GUIDE_FLAG_CONTRACTS],
+  ["search", SEARCH_FLAG_CONTRACTS],
+  ["next", NEXT_FLAG_CONTRACTS],
+  ["eval", EVAL_FLAG_CONTRACTS],
+  ["history", HISTORY_FLAG_CONTRACTS],
+  ["history-redact", HISTORY_REDACT_FLAG_CONTRACTS],
+  ["history-repair", HISTORY_REPAIR_FLAG_CONTRACTS],
+  ["history-compact", HISTORY_COMPACT_FLAG_CONTRACTS],
+  ["schema", SCHEMA_FLAG_CONTRACTS],
+  ["profile", PROFILE_FLAG_CONTRACTS],
+  ["plan", PLAN_FLAG_CONTRACTS],
+  ["activity", ACTIVITY_FLAG_CONTRACTS],
+  ["restore", RESTORE_FLAG_CONTRACTS],
+  ["update", UPDATE_FLAG_CONTRACTS],
+  ["update-many", UPDATE_MANY_FLAG_CONTRACTS],
+  ["close", CLOSE_FLAG_CONTRACTS],
+  ["close-many", CLOSE_MANY_FLAG_CONTRACTS],
+  ["delete", DELETE_FLAG_CONTRACTS],
+  ["append", APPEND_FLAG_CONTRACTS],
+  ["comments", COMMENTS_FLAG_CONTRACTS],
+  ["comments-audit", COMMENTS_AUDIT_FLAG_CONTRACTS],
+  ["notes", NOTES_FLAG_CONTRACTS],
+  ["learnings", LEARNINGS_FLAG_CONTRACTS],
+  ["files", FILES_FLAG_CONTRACTS],
+  ["docs", DOCS_FLAG_CONTRACTS],
+  ["deps", DEPS_FLAG_CONTRACTS],
+  ["test", TEST_FLAG_CONTRACTS],
+  ["test-all", TEST_ALL_FLAG_CONTRACTS],
+  ["telemetry", TELEMETRY_FLAG_CONTRACTS],
+  ["health", HEALTH_FLAG_CONTRACTS],
+  ["validate", VALIDATE_FLAG_CONTRACTS],
+  ["gc", GC_FLAG_CONTRACTS],
+  ["stats", STATS_FLAG_CONTRACTS],
+  ["contracts", CONTRACTS_FLAG_CONTRACTS],
+  ["completion", COMPLETION_FLAG_CONTRACTS],
+  ["claim", CLAIM_FLAG_CONTRACTS],
+  ["release", RELEASE_FLAG_CONTRACTS],
+  ["start-task", START_TASK_FLAG_CONTRACTS],
+  ["pause-task", PAUSE_TASK_FLAG_CONTRACTS],
+  ["close-task", CLOSE_TASK_FLAG_CONTRACTS],
+  ["meet", MEET_FLAG_CONTRACTS],
+  ["event", EVENT_FLAG_CONTRACTS],
+  ["remind", REMIND_FLAG_CONTRACTS]
+]);
+var EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND = /* @__PURE__ */ new Map([
+  ["install", EXTENSION_INSTALL_FLAG_CONTRACTS],
+  ["uninstall", EXTENSION_UNINSTALL_FLAG_CONTRACTS],
+  ["explore", EXTENSION_EXPLORE_FLAG_CONTRACTS],
+  ["manage", EXTENSION_MANAGE_FLAG_CONTRACTS],
+  ["describe", EXTENSION_DESCRIBE_FLAG_CONTRACTS],
+  ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
+  ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
+  ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
+  ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
+  ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
+  ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
+  ["deactivate", EXTENSION_DEACTIVATE_FLAG_CONTRACTS]
+]);
+function normalizeCommandNameForContracts(commandName) {
+  if (typeof commandName !== "string") {
+    return "";
+  }
+  return commandName.trim().toLowerCase();
+}
+function resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand) {
+  if (lifecycleSubcommand === "init") {
+    return rootCommand === "extension" ? EXTENSION_INIT_FLAG_CONTRACTS : PACKAGE_INIT_FLAG_CONTRACTS;
+  }
+  return EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND.get(lifecycleSubcommand) ?? [];
+}
+function resolveSubcommandFlagContractsForCommand(commandName) {
+  const normalized = normalizeCommandNameForContracts(commandName);
+  if (normalized.length === 0) {
+    return withSubcommandGlobalFlags([]);
+  }
+  const [rootCommand, lifecycleSubcommand, ...extraParts] = normalized.split(/\s+/);
+  if ((rootCommand === "extension" || rootCommand === "package" || rootCommand === "packages") && lifecycleSubcommand !== void 0 && extraParts.length === 0) {
+    return withSubcommandGlobalFlags(resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand));
+  }
+  return withSubcommandGlobalFlags(SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND.get(normalized) ?? []);
+}
+
+// dist/sdk/cli-contracts/tool-option-contracts.js
+function cloneOptionContracts(contracts) {
+  return contracts.map((contract) => ({ ...contract }));
+}
+var TOOL_ITEM_BASE_FILTER_OPTION_CONTRACTS = [
+  { param: "status", flag: "--status" },
+  { param: "type", flag: "--type" },
+  { param: "tag", flag: "--tag" },
+  { param: "priority", flag: "--priority" },
+  { param: "deadlineBefore", flag: "--deadline-before" },
+  { param: "deadlineAfter", flag: "--deadline-after" }
+];
+var TOOL_ITEM_WINDOW_FILTER_OPTION_CONTRACTS = [
+  { param: "updatedAfter", flag: "--updated-after" },
+  { param: "updatedBefore", flag: "--updated-before" },
+  { param: "createdAfter", flag: "--created-after" },
+  { param: "createdBefore", flag: "--created-before" }
+];
+var TOOL_ITEM_RELATION_FILTER_OPTION_CONTRACTS = [
+  { param: "assignee", flag: "--assignee" },
+  { param: "assigneeFilter", flag: "--assignee-filter" },
+  { param: "parent", flag: "--parent" },
+  { param: "sprint", flag: "--sprint" },
+  { param: "release", flag: "--release" }
+];
+var TOOL_SEARCH_RELATION_FILTER_OPTION_CONTRACTS = [
+  { param: "assignee", flag: "--assignee" },
+  { param: "sprint", flag: "--sprint" },
+  { param: "release", flag: "--release" },
+  { param: "parent", flag: "--parent" }
+];
+var TOOL_BASIC_ITEM_FILTER_OPTION_CONTRACTS = [
+  ...TOOL_ITEM_BASE_FILTER_OPTION_CONTRACTS,
+  ...TOOL_ITEM_RELATION_FILTER_OPTION_CONTRACTS
+];
+var TOOL_GOVERNANCE_MISSING_OPTION_CONTRACTS = [
+  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
+  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
+  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
+  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
+  { param: "filterReleaseMissing", flag: "--filter-release-missing" }
+];
+var TOOL_CONTENT_PRESENCE_OPTION_CONTRACTS = [
+  { param: "hasNotes", flag: "--has-notes" },
+  { param: "noNotes", flag: "--no-notes" },
+  { param: "hasLearnings", flag: "--has-learnings" },
+  { param: "noLearnings", flag: "--no-learnings" },
+  { param: "hasFiles", flag: "--has-files" },
+  { param: "noFiles", flag: "--no-files" },
+  { param: "hasDocs", flag: "--has-docs" },
+  { param: "noDocs", flag: "--no-docs" },
+  { param: "hasTests", flag: "--has-tests" },
+  { param: "noTests", flag: "--no-tests" },
+  { param: "hasComments", flag: "--has-comments" },
+  { param: "noComments", flag: "--no-comments" },
+  { param: "hasDeps", flag: "--has-deps" },
+  { param: "noDeps", flag: "--no-deps" },
+  { param: "hasBody", flag: "--has-body" },
+  { param: "emptyBody", flag: "--empty-body" },
+  { param: "hasLinkedCommand", flag: "--has-linked-command" },
+  { param: "noLinkedCommand", flag: "--no-linked-command" }
+];
+var TOOL_LIST_FILTER_OPTION_CONTRACTS = [
+  ...cloneOptionContracts(TOOL_ITEM_BASE_FILTER_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_ITEM_WINDOW_FILTER_OPTION_CONTRACTS),
+  { param: "ids", flag: "--ids" },
+  ...cloneOptionContracts(TOOL_ITEM_RELATION_FILTER_OPTION_CONTRACTS),
+  { param: "filterAcMissing", flag: "--filter-ac-missing" },
+  { param: "filterEstimatesMissing", flag: "--filter-estimates-missing" },
+  { param: "filterResolutionMissing", flag: "--filter-resolution-missing" },
+  { param: "filterMetadataMissing", flag: "--filter-metadata-missing" },
+  ...cloneOptionContracts(TOOL_GOVERNANCE_MISSING_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_CONTENT_PRESENCE_OPTION_CONTRACTS),
+  { param: "limit", flag: "--limit" },
+  { param: "offset", flag: "--offset" },
+  { param: "fields", flag: "--fields" },
+  { param: "sort", flag: "--sort" },
+  { param: "order", flag: "--order" },
+  { param: "tree", flag: "--tree" },
+  { param: "treeDepth", flag: "--tree-depth" }
+];
+var TOOL_AGGREGATE_OPTION_CONTRACTS = [
+  { param: "groupBy", flag: "--group-by" },
+  { param: "sum", flag: "--sum" },
+  { param: "avg", flag: "--avg" },
+  ...cloneOptionContracts(TOOL_BASIC_ITEM_FILTER_OPTION_CONTRACTS)
+];
+var TOOL_DEDUPE_AUDIT_OPTION_CONTRACTS = [
+  { param: "mode", flag: "--mode" },
+  { param: "limit", flag: "--limit" },
+  { param: "threshold", flag: "--threshold" },
+  ...cloneOptionContracts(TOOL_BASIC_ITEM_FILTER_OPTION_CONTRACTS)
+];
+var TOOL_SEARCH_FILTER_OPTION_CONTRACTS = [
+  { param: "matchMode", flag: "--match-mode" },
+  { param: "minScore", flag: "--min-score" },
+  { param: "count", flag: "--count", booleanish: true },
+  { param: "semanticWeight", flag: "--semantic-weight" },
+  ...cloneOptionContracts(TOOL_ITEM_BASE_FILTER_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_ITEM_WINDOW_FILTER_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_SEARCH_RELATION_FILTER_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_GOVERNANCE_MISSING_OPTION_CONTRACTS),
+  ...cloneOptionContracts(TOOL_CONTENT_PRESENCE_OPTION_CONTRACTS),
+  { param: "fields", flag: "--fields" },
+  { param: "limit", flag: "--limit" }
+];
+var TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS = [
+  { param: "parent", flag: "--parent" },
+  { param: "reviewer", flag: "--reviewer" },
+  { param: "risk", flag: "--risk" },
+  { param: "confidence", flag: "--confidence" },
+  { param: "sprint", flag: "--sprint" },
+  { param: "release", flag: "--release" },
+  { param: "blockedBy", flag: "--blocked-by" },
+  { param: "blockedReason", flag: "--blocked-reason" },
+  { param: "unblockNote", flag: "--unblock-note" },
+  { param: "reporter", flag: "--reporter" },
+  { param: "severity", flag: "--severity" },
+  { param: "environment", flag: "--environment" },
+  { param: "reproSteps", flag: "--repro-steps" },
+  { param: "resolution", flag: "--resolution" },
+  { param: "expectedResult", flag: "--expected-result" },
+  { param: "actualResult", flag: "--actual-result" },
+  { param: "affectedVersion", flag: "--affected-version" },
+  { param: "fixedVersion", flag: "--fixed-version" },
+  { param: "component", flag: "--component" },
+  { param: "regression", flag: "--regression", booleanish: true },
+  { param: "customerImpact", flag: "--customer-impact" },
+  { param: "definitionOfReady", flag: "--definition-of-ready", allowEmpty: true },
+  { param: "order", flag: "--order" },
+  { param: "goal", flag: "--goal" },
+  { param: "objective", flag: "--objective" },
+  { param: "value", flag: "--value" },
+  { param: "impact", flag: "--impact" },
+  { param: "outcome", flag: "--outcome" },
+  { param: "whyNow", flag: "--why-now" }
+];
+var TOOL_CREATE_OPTION_CONTRACTS = [
+  { param: "title", flag: "--title" },
+  { param: "description", flag: "--description", allowEmpty: true },
+  { param: "type", flag: "--type" },
+  { param: "template", flag: "--template" },
+  { param: "createMode", flag: "--create-mode" },
+  { param: "schedulePreset", flag: "--schedule-preset" },
+  { param: "status", flag: "--status" },
+  { param: "priority", flag: "--priority" },
+  { param: "tags", flag: "--tags", allowEmpty: true },
+  { param: "addTags", flag: "--add-tags", repeatable: true },
+  { param: "body", flag: "--body", allowEmpty: true },
+  { param: "deadline", flag: "--deadline" },
+  { param: "estimate", flag: "--estimate" },
+  { param: "acceptanceCriteria", flag: "--acceptance-criteria", allowEmpty: true },
+  { param: "author", flag: "--author" },
+  { param: "message", flag: "--message", allowEmpty: true },
+  { param: "assignee", flag: "--assignee" },
+  { param: "allowMissingParent", flag: "--allow-missing-parent" },
+  { param: "reminder", flag: "--reminder", repeatable: true },
+  { param: "event", flag: "--event", repeatable: true },
+  { param: "typeOption", flag: "--type-option", repeatable: true },
+  { param: "field", flag: "--field", repeatable: true },
+  { param: "dep", flag: "--dep", repeatable: true },
+  { param: "comment", flag: "--comment", repeatable: true },
+  { param: "note", flag: "--note", repeatable: true },
+  { param: "learning", flag: "--learning", repeatable: true },
+  { param: "linkedFile", flag: "--file", repeatable: true },
+  { param: "linkedTest", flag: "--test", repeatable: true },
+  { param: "doc", flag: "--doc", repeatable: true },
+  { param: "unset", flag: "--unset", repeatable: true },
+  { param: "clearDeps", flag: "--clear-deps" },
+  { param: "clearComments", flag: "--clear-comments" },
+  { param: "clearNotes", flag: "--clear-notes" },
+  { param: "clearLearnings", flag: "--clear-learnings" },
+  { param: "clearFiles", flag: "--clear-files" },
+  { param: "clearTests", flag: "--clear-tests" },
+  { param: "clearDocs", flag: "--clear-docs" },
+  { param: "clearReminders", flag: "--clear-reminders" },
+  { param: "clearEvents", flag: "--clear-events" },
+  { param: "clearTypeOptions", flag: "--clear-type-options" }
 ];
-var GET_FLAG_CONTRACTS = [
-  { flag: "--depth" },
-  { flag: "--full" },
-  { flag: "--fields", list: true },
-  { flag: "--tree" },
-  { flag: "--tree-depth" },
-  { flag: "--tree_depth" },
-  { flag: "--format" }
+var TOOL_UPDATE_OPTION_CONTRACTS = [
+  { param: "title", flag: "--title" },
+  { param: "description", flag: "--description", allowEmpty: true },
+  { param: "body", flag: "--body", allowEmpty: true },
+  { param: "status", flag: "--status" },
+  { param: "closeReason", flag: "--close-reason" },
+  { param: "priority", flag: "--priority" },
+  { param: "type", flag: "--type" },
+  { param: "tags", flag: "--tags", allowEmpty: true },
+  { param: "addTags", flag: "--add-tags", repeatable: true },
+  { param: "removeTags", flag: "--remove-tags", repeatable: true },
+  { param: "deadline", flag: "--deadline" },
+  { param: "estimate", flag: "--estimate" },
+  { param: "acceptanceCriteria", flag: "--acceptance-criteria", allowEmpty: true },
+  { param: "author", flag: "--author" },
+  { param: "message", flag: "--message", allowEmpty: true },
+  { param: "assignee", flag: "--assignee" },
+  { param: "dep", flag: "--dep", repeatable: true },
+  { param: "depRemove", flag: "--dep-remove", repeatable: true },
+  { param: "replaceDeps", flag: "--replace-deps" },
+  { param: "replaceTests", flag: "--replace-tests" },
+  { param: "comment", flag: "--comment", repeatable: true },
+  { param: "note", flag: "--note", repeatable: true },
+  { param: "learning", flag: "--learning", repeatable: true },
+  { param: "linkedFile", flag: "--file", repeatable: true },
+  { param: "linkedTest", flag: "--test", repeatable: true },
+  { param: "doc", flag: "--doc", repeatable: true },
+  { param: "reminder", flag: "--reminder", repeatable: true },
+  { param: "event", flag: "--event", repeatable: true },
+  { param: "typeOption", flag: "--type-option", repeatable: true },
+  { param: "field", flag: "--field", repeatable: true },
+  { param: "unset", flag: "--unset", repeatable: true },
+  { param: "clearDeps", flag: "--clear-deps" },
+  { param: "clearComments", flag: "--clear-comments" },
+  { param: "clearNotes", flag: "--clear-notes" },
+  { param: "clearLearnings", flag: "--clear-learnings" },
+  { param: "clearFiles", flag: "--clear-files" },
+  { param: "clearTests", flag: "--clear-tests" },
+  { param: "clearDocs", flag: "--clear-docs" },
+  { param: "clearReminders", flag: "--clear-reminders" },
+  { param: "clearEvents", flag: "--clear-events" },
+  { param: "clearTypeOptions", flag: "--clear-type-options" },
+  { param: "allowAuditUpdate", flag: "--allow-audit-update" },
+  { param: "allowAuditDepUpdate", flag: "--allow-audit-dep-update" }
 ];
-var GUIDE_FLAG_CONTRACTS = [
-  { flag: "--list" },
-  { flag: "--format" },
-  { flag: "--depth" }
+var TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACTS = [
+  { param: "filterStatus", flag: "--filter-status" },
+  { param: "filterType", flag: "--filter-type" },
+  { param: "filterTag", flag: "--filter-tag" },
+  { param: "filterPriority", flag: "--filter-priority" },
+  { param: "filterDeadlineBefore", flag: "--filter-deadline-before" },
+  { param: "filterDeadlineAfter", flag: "--filter-deadline-after" },
+  { param: "filterUpdatedAfter", flag: "--filter-updated-after" },
+  { param: "filterUpdatedBefore", flag: "--filter-updated-before" },
+  { param: "filterCreatedAfter", flag: "--filter-created-after" },
+  { param: "filterCreatedBefore", flag: "--filter-created-before" },
+  { param: "filterAssignee", flag: "--filter-assignee" },
+  { param: "filterAssigneeFilter", flag: "--filter-assignee-filter" },
+  { param: "filterParent", flag: "--filter-parent" },
+  { param: "filterSprint", flag: "--filter-sprint" },
+  { param: "filterRelease", flag: "--filter-release" },
+  { param: "filterReviewerMissing", flag: "--filter-reviewer-missing" },
+  { param: "filterRiskMissing", flag: "--filter-risk-missing" },
+  { param: "filterConfidenceMissing", flag: "--filter-confidence-missing" },
+  { param: "filterSprintMissing", flag: "--filter-sprint-missing" },
+  { param: "filterReleaseMissing", flag: "--filter-release-missing" },
+  { param: "filterHasNotes", flag: "--filter-has-notes" },
+  { param: "filterNoNotes", flag: "--filter-no-notes" },
+  { param: "filterHasLearnings", flag: "--filter-has-learnings" },
+  { param: "filterNoLearnings", flag: "--filter-no-learnings" },
+  { param: "filterHasFiles", flag: "--filter-has-files" },
+  { param: "filterNoFiles", flag: "--filter-no-files" },
+  { param: "filterHasDocs", flag: "--filter-has-docs" },
+  { param: "filterNoDocs", flag: "--filter-no-docs" },
+  { param: "filterHasTests", flag: "--filter-has-tests" },
+  { param: "filterNoTests", flag: "--filter-no-tests" },
+  { param: "filterHasComments", flag: "--filter-has-comments" },
+  { param: "filterNoComments", flag: "--filter-no-comments" },
+  { param: "filterHasDeps", flag: "--filter-has-deps" },
+  { param: "filterNoDeps", flag: "--filter-no-deps" },
+  { param: "filterHasBody", flag: "--filter-has-body" },
+  { param: "filterEmptyBody", flag: "--filter-empty-body" },
+  { param: "filterHasLinkedCommand", flag: "--filter-has-linked-command" },
+  { param: "filterNoLinkedCommand", flag: "--filter-no-linked-command" },
+  { param: "ids", flag: "--ids" },
+  { param: "limit", flag: "--limit" },
+  { param: "offset", flag: "--offset" }
 ];
-var DEPS_FLAG_CONTRACTS = [
-  { flag: "--format" },
-  { flag: "--max-depth" },
-  { flag: "--collapse" },
-  { flag: "--summary" }
+var TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS = [
+  ...cloneOptionContracts(TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACTS)
 ];
-var EVAL_FLAG_CONTRACTS = [
-  { flag: "--mode" },
-  { flag: "--k" },
-  { flag: "--fail-under" },
-  { flag: "--queries" },
-  { flag: "--format" }
+var TOOL_NORMALIZE_FILTER_OPTION_CONTRACTS = [
+  { param: "filterStatus", flag: "--filter-status" },
+  { param: "filterType", flag: "--filter-type" },
+  { param: "filterTag", flag: "--filter-tag" },
+  { param: "filterPriority", flag: "--filter-priority" },
+  { param: "filterDeadlineBefore", flag: "--filter-deadline-before" },
+  { param: "filterDeadlineAfter", flag: "--filter-deadline-after" },
+  { param: "filterAssignee", flag: "--filter-assignee" },
+  { param: "filterAssigneeFilter", flag: "--filter-assignee-filter" },
+  { param: "filterParent", flag: "--filter-parent" },
+  { param: "filterSprint", flag: "--filter-sprint" },
+  { param: "filterRelease", flag: "--filter-release" },
+  { param: "limit", flag: "--limit" },
+  { param: "offset", flag: "--offset" }
 ];
-var SEARCH_FLAG_CONTRACTS = [
-  { flag: "--mode" },
-  { flag: "--semantic" },
-  { flag: "--hybrid" },
-  { flag: "--match-mode" },
-  { flag: "--min-score" },
-  { flag: "--count" },
-  { flag: "--semantic-weight" },
-  { flag: "--include-linked" },
-  { flag: "--title-exact" },
-  { flag: "--phrase-exact" },
-  { flag: "--highlight" },
-  { flag: "--compact" },
-  { flag: "--full" },
-  { flag: "--fields", list: true },
-  { flag: "--format" },
-  { flag: "--limit" },
-  { flag: "--status", list: true },
-  { flag: "--type" },
-  { flag: "--tag", aliases: ["--tags"] },
-  { flag: "--priority" },
-  { flag: "--deadline-before" },
-  { flag: "--deadline-after" },
-  { flag: "--updated-after" },
-  { flag: "--updated-before" },
-  { flag: "--created-after" },
-  { flag: "--created-before" },
-  { flag: "--assignee" },
-  { flag: "--sprint" },
-  { flag: "--release" },
-  { flag: "--parent" },
-  { flag: "--filter-reviewer-missing" },
-  { flag: "--filter-risk-missing" },
-  { flag: "--filter-confidence-missing" },
-  { flag: "--filter-sprint-missing" },
-  { flag: "--filter-release-missing" },
-  { flag: "--has-notes" },
-  { flag: "--no-notes" },
-  { flag: "--has-learnings" },
-  { flag: "--no-learnings" },
-  { flag: "--has-files" },
-  { flag: "--no-files" },
-  { flag: "--has-docs" },
-  { flag: "--no-docs" },
-  { flag: "--has-tests" },
-  { flag: "--no-tests" },
-  { flag: "--has-comments" },
-  { flag: "--no-comments" },
-  { flag: "--has-deps" },
-  { flag: "--no-deps" },
-  { flag: "--has-body" },
-  { flag: "--empty-body" },
-  { flag: "--has-linked-command" },
-  { flag: "--no-linked-command" }
+var TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS = [
+  ...cloneOptionContracts(TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACTS)
 ];
-var CONTRACTS_FLAG_CONTRACTS = [
-  { flag: "--action" },
-  { flag: "--command" },
-  { flag: "--schema-only" },
-  { flag: "--flags-only" },
-  { flag: "--availability-only" },
-  { flag: "--runtime-only" },
-  { flag: "--active-only" },
-  { flag: "--full" }
+var TOOL_ACTIVITY_OPTION_CONTRACTS = [
+  { param: "id", flag: "--id" },
+  { param: "op", flag: "--op" },
+  { param: "author", flag: "--author" },
+  { param: "from", flag: "--from" },
+  { param: "to", flag: "--to" },
+  { param: "limit", flag: "--limit" },
+  { param: "compact", flag: "--compact" },
+  { param: "full", flag: "--full" }
 ];
-var COMPLETION_FLAG_CONTRACTS = [
-  { flag: "--eager-tags" }
+var TOOL_CONTEXT_OPTION_CONTRACTS = [
+  { param: "date", flag: "--date" },
+  { param: "from", flag: "--from" },
+  { param: "to", flag: "--to" },
+  { param: "type", flag: "--type" },
+  { param: "tag", flag: "--tag" },
+  { param: "priority", flag: "--priority" },
+  { param: "assignee", flag: "--assignee" },
+  { param: "assigneeFilter", flag: "--assignee-filter" },
+  { param: "sprint", flag: "--sprint" },
+  { param: "release", flag: "--release" },
+  { param: "parent", flag: "--parent" },
+  { param: "limit", flag: "--limit" },
+  { param: "format", flag: "--format" },
+  { param: "depth", flag: "--depth" },
+  { param: "fields", flag: "--fields" },
+  { param: "section", flag: "--section", repeatable: true },
+  { param: "activityLimit", flag: "--activity-limit" },
+  { param: "staleThreshold", flag: "--stale-threshold" }
+];
+
+// dist/sdk/cli-contracts/tool-parameter-tables.js
+var PM_TOOL_PARAMETER_PROPERTIES = {
+  json: { type: "boolean", default: true },
+  quiet: { type: "boolean" },
+  profile: { type: "boolean" },
+  noExtensions: { type: "boolean" },
+  noPager: { type: "boolean" },
+  path: { type: "string" },
+  pmExecutable: { type: "string" },
+  timeoutMs: { type: "number" },
+  id: { type: "string" },
+  target: { type: "string" },
+  output: { type: "string", minLength: 1 },
+  github: { type: "string" },
+  ref: { type: "string" },
+  query: { type: "string" },
+  keywords: { type: "string" },
+  fields: { type: "string" },
+  sort: { type: "string", enum: ["priority", "deadline", "updated_at", "created_at", "title", "parent"] },
+  prefix: { type: "string" },
+  preset: { type: "string", enum: ["minimal", "default", "strict", "custom"] },
+  typePreset: { type: "string", enum: ["agile", "ops", "research"] },
+  defaults: { type: "boolean" },
+  verbose: { type: "boolean" },
+  agentGuidance: { type: "string", enum: ["ask", "add", "skip", "status"] },
+  withPackages: { type: "boolean" },
+  scope: { type: "string", enum: ["project", "global"] },
+  allOver: { type: "number" },
+  minEntries: { type: "number" },
+  closed: { type: "boolean" },
+  allStreams: { type: "boolean" },
+  contractAction: { type: "string" },
+  command: { type: "string" },
+  schemaOnly: { type: "boolean" },
+  flagsOnly: { type: "boolean" },
+  availabilityOnly: { type: "boolean" },
+  runtimeOnly: { type: "boolean" },
+  activeOnly: { type: "boolean" },
+  eagerTags: { type: "boolean" },
+  fullChangedFields: { type: "boolean" },
+  idOnly: { type: "boolean" },
+  allowMissingParent: { type: "boolean" },
+  duplicateOf: { type: "string" },
+  configAction: { type: "string", enum: ["get", "set", "list", "export"] },
+  key: { type: "string" },
+  title: { type: "string" },
+  description: { type: "string" },
+  type: { type: "string" },
+  template: { type: "string" },
+  createMode: { type: "string", enum: ["strict", "progressive"] },
+  schedulePreset: { type: "string", enum: ["lightweight"] },
+  status: { type: "string" },
+  filterStatus: { type: "string" },
+  filterType: { type: "string" },
+  filterTag: { type: "string" },
+  filterPriority: { anyOf: [{ type: "string" }, { type: "number" }] },
+  filterDeadlineBefore: { type: "string" },
+  filterDeadlineAfter: { type: "string" },
+  filterUpdatedAfter: { type: "string" },
+  filterUpdatedBefore: { type: "string" },
+  filterCreatedAfter: { type: "string" },
+  filterCreatedBefore: { type: "string" },
+  filterAssignee: { type: "string" },
+  filterAssigneeFilter: { type: "string", enum: ["assigned", "unassigned"] },
+  filterParent: { type: "string" },
+  filterSprint: { type: "string" },
+  filterRelease: { type: "string" },
+  closeReason: { type: "string" },
+  reason: { type: "string" },
+  priority: { anyOf: [{ type: "string" }, { type: "number" }] },
+  tags: { type: "string" },
+  addTags: { type: "array", items: { type: "string" } },
+  removeTags: { type: "array", items: { type: "string" } },
+  body: { type: "string" },
+  deadline: { type: "string" },
+  estimate: { anyOf: [{ type: "string" }, { type: "number" }] },
+  acceptanceCriteria: { type: "string" },
+  author: { type: "string" },
+  message: { type: "string" },
+  assignee: { type: "string" },
+  assigneeFilter: { type: "string", enum: ["assigned", "unassigned"] },
+  parent: { type: "string" },
+  reviewer: { type: "string" },
+  risk: { type: "string" },
+  confidence: { anyOf: [{ type: "string" }, { type: "number" }] },
+  sprint: { type: "string" },
+  release: { type: "string" },
+  blockedBy: { type: "string" },
+  blockedReason: { type: "string" },
+  unblockNote: { type: "string" },
+  reporter: { type: "string" },
+  severity: { type: "string" },
+  environment: { type: "string" },
+  reproSteps: { type: "string" },
+  resolution: { type: "string" },
+  expectedResult: { type: "string" },
+  actualResult: { type: "string" },
+  affectedVersion: { type: "string" },
+  fixedVersion: { type: "string" },
+  component: { type: "string" },
+  regression: { anyOf: [{ type: "boolean" }, { type: "string" }, { type: "number" }] },
+  customerImpact: { type: "string" },
+  definitionOfReady: { type: "string" },
+  order: { anyOf: [{ type: "string" }, { type: "number" }] },
+  goal: { type: "string" },
+  objective: { type: "string" },
+  value: { type: "string" },
+  impact: { type: "string" },
+  outcome: { type: "string" },
+  whyNow: { type: "string" },
+  mode: {
+    type: "string",
+    enum: ["keyword", "semantic", "hybrid", "title_exact", "title_fuzzy", "parent_scope"]
+  },
+  semanticWeight: { anyOf: [{ type: "string" }, { type: "number" }] },
+  op: { type: "string" },
+  compact: { type: "boolean" },
+  brief: { type: "boolean" },
+  full: { type: "boolean" },
+  view: { type: "string", enum: ["agenda", "day", "week", "month"] },
+  date: { type: "string" },
+  from: { type: "string" },
+  before: { type: "string" },
+  to: { type: "string" },
+  past: { type: "boolean" },
+  fullPeriod: { type: "boolean" },
+  include: { type: "string" },
+  recurrenceLookaheadDays: { anyOf: [{ type: "string" }, { type: "number" }] },
+  recurrenceLookbackDays: { anyOf: [{ type: "string" }, { type: "number" }] },
+  occurrenceLimit: { anyOf: [{ type: "string" }, { type: "number" }] },
+  includeLinked: { type: "boolean" },
+  semantic: { type: "boolean" },
+  hybrid: { type: "boolean" },
+  titleExact: { type: "boolean" },
+  phraseExact: { type: "boolean" },
+  highlight: { type: "boolean" },
+  includeBody: { type: "boolean" },
+  noTruncate: { type: "boolean" },
+  tag: { type: "string" },
+  deadlineBefore: { type: "string" },
+  deadlineAfter: { type: "string" },
+  updatedAfter: { type: "string" },
+  updatedBefore: { type: "string" },
+  createdAfter: { type: "string" },
+  createdBefore: { type: "string" },
+  filterAcMissing: { type: "boolean" },
+  filterEstimatesMissing: { type: "boolean" },
+  filterResolutionMissing: { type: "boolean" },
+  filterMetadataMissing: { type: "boolean" },
+  filterReviewerMissing: { type: "boolean" },
+  filterRiskMissing: { type: "boolean" },
+  filterConfidenceMissing: { type: "boolean" },
+  filterSprintMissing: { type: "boolean" },
+  filterReleaseMissing: { type: "boolean" },
+  // Content-field presence/absence filters (list/search). The --no-* variants
+  // select items where the field is empty/absent.
+  hasNotes: { type: "boolean" },
+  noNotes: { type: "boolean" },
+  hasLearnings: { type: "boolean" },
+  noLearnings: { type: "boolean" },
+  hasFiles: { type: "boolean" },
+  noFiles: { type: "boolean" },
+  hasDocs: { type: "boolean" },
+  noDocs: { type: "boolean" },
+  hasTests: { type: "boolean" },
+  noTests: { type: "boolean" },
+  hasComments: { type: "boolean" },
+  noComments: { type: "boolean" },
+  hasDeps: { type: "boolean" },
+  noDeps: { type: "boolean" },
+  hasBody: { type: "boolean" },
+  emptyBody: { type: "boolean" },
+  hasLinkedCommand: { type: "boolean" },
+  noLinkedCommand: { type: "boolean" },
+  // Bulk-selection (update-many/close-many) content + governance filters mirror
+  // the list/search presence filters under the --filter- prefix.
+  filterHasNotes: { type: "boolean" },
+  filterNoNotes: { type: "boolean" },
+  filterHasLearnings: { type: "boolean" },
+  filterNoLearnings: { type: "boolean" },
+  filterHasFiles: { type: "boolean" },
+  filterNoFiles: { type: "boolean" },
+  filterHasDocs: { type: "boolean" },
+  filterNoDocs: { type: "boolean" },
+  filterHasTests: { type: "boolean" },
+  filterNoTests: { type: "boolean" },
+  filterHasComments: { type: "boolean" },
+  filterNoComments: { type: "boolean" },
+  filterHasDeps: { type: "boolean" },
+  filterNoDeps: { type: "boolean" },
+  filterHasBody: { type: "boolean" },
+  filterEmptyBody: { type: "boolean" },
+  filterHasLinkedCommand: { type: "boolean" },
+  filterNoLinkedCommand: { type: "boolean" },
+  ids: { type: "string" },
+  limit: { anyOf: [{ type: "string" }, { type: "number" }] },
+  blockedLimit: { anyOf: [{ type: "string" }, { type: "number" }] },
+  readyOnly: { type: "boolean" },
+  limitItems: { anyOf: [{ type: "string" }, { type: "number" }] },
+  fullHistory: { type: "boolean" },
+  latest: { anyOf: [{ type: "string" }, { type: "number" }] },
+  offset: { anyOf: [{ type: "string" }, { type: "number" }] },
+  progress: { type: "boolean" },
+  background: { type: "boolean" },
+  runId: { type: "string" },
+  stream: {
+    anyOf: [{ type: "boolean" }, { type: "string", enum: ["stdout", "stderr", "both", "rows", "ndjson", "jsonl"] }]
+  },
+  tail: { anyOf: [{ type: "string" }, { type: "number" }] },
+  addJson: { type: "array", items: { type: "string" } },
+  match: { type: "string" },
+  onlyIndex: { anyOf: [{ type: "string" }, { type: "number" }] },
+  onlyLast: { type: "boolean" },
+  envSet: { type: "array", items: { type: "string" } },
+  envClear: { type: "array", items: { type: "string" } },
+  sharedHostSafe: { type: "boolean" },
+  detail: { type: "string", enum: ["summary", "deep"] },
+  trace: { type: "boolean" },
+  reload: { type: "boolean" },
+  watch: { type: "boolean" },
+  runtimeProbe: { type: "boolean" },
+  fixManagedState: { type: "boolean" },
+  pmContext: { type: "string", enum: ["schema", "tracker", "auto"] },
+  overrideLinkedPmContext: { type: "boolean" },
+  failOnContextMismatch: { type: "boolean" },
+  failOnSkipped: { type: "boolean" },
+  failOnEmptyTestRun: { type: "boolean" },
+  requireAssertionsForPm: { type: "boolean" },
+  checkContext: { type: "boolean" },
+  autoPmContext: { type: "boolean" },
+  diff: { type: "boolean" },
+  storage: { type: "boolean" },
+  metadataCoverage: { type: "boolean" },
+  fieldUtilization: { type: "boolean" },
+  byAssignee: { type: "boolean" },
+  byTag: { type: "boolean" },
+  byPriority: { type: "boolean" },
+  tagPrefix: { type: "string" },
+  verify: { type: "boolean" },
+  literal: { type: "array", items: { type: "string" } },
+  regex: { type: "array", items: { type: "string" } },
+  replacement: { type: "string" },
+  timeout: { anyOf: [{ type: "string" }, { type: "number" }] },
+  validateClose: { type: "string", enum: ["off", "warn", "strict"] },
+  checkMetadata: { type: "boolean" },
+  metadataProfile: { type: "string", enum: ["core", "strict", "custom"] },
+  checkResolution: { type: "boolean" },
+  checkLifecycle: { type: "boolean" },
+  checkStaleBlockers: { type: "boolean" },
+  dependencyCycleSeverity: { type: "string", enum: ["off", "warn", "error"] },
+  parentCycleSeverity: { type: "string", enum: ["off", "warn", "error"] },
+  checkFiles: { type: "boolean" },
+  strictDirectories: { type: "boolean" },
+  checkOnly: { type: "boolean" },
+  checkTelemetry: { type: "boolean" },
+  noRefresh: { type: "boolean" },
+  refreshVectors: { type: "boolean" },
+  verboseStaleItems: { type: "boolean" },
+  skipVectors: { type: "boolean" },
+  skipIntegrity: { type: "boolean" },
+  skipDrift: { type: "boolean" },
+  verboseDiagnostics: { type: "boolean" },
+  allAffectedIds: { type: "boolean" },
+  scanMode: { type: "string", enum: ["default", "tracked-all", "tracked-all-strict"] },
+  includePmInternals: { type: "boolean" },
+  verboseFileLists: { type: "boolean" },
+  strictExit: { type: "boolean" },
+  failOnWarn: { type: "boolean" },
+  fixHints: { type: "boolean" },
+  autoFix: { type: "boolean" },
+  fixScope: { type: "array", items: { type: "string", enum: ["metadata", "resolution", "estimates", "lifecycle"] } },
+  pruneMissing: { type: "boolean" },
+  checkHistoryDrift: { type: "boolean" },
+  checkCommandReferences: { type: "boolean" },
+  allowAuditNote: { type: "boolean" },
+  allowAuditLearning: { type: "boolean" },
+  allowAuditComment: { type: "boolean" },
+  edit: { type: "integer", minimum: 1 },
+  delete: { type: "integer", minimum: 1 },
+  allowAuditUpdate: { type: "boolean" },
+  allowAuditDepUpdate: { type: "boolean" },
+  allowAuditRelease: { type: "boolean" },
+  dryRun: { type: "boolean" },
+  all: { type: "boolean" },
+  clear: { type: "boolean" },
+  cliOnly: { type: "boolean" },
+  packagesOnly: { type: "boolean" },
+  repair: { type: "boolean" },
+  packageName: { type: "string" },
+  rollback: { type: "string" },
+  noCheckpoint: { type: "boolean" },
+  force: { type: "boolean" },
+  run: { type: "boolean" },
+  count: { type: "boolean" },
+  sum: { type: "string" },
+  avg: { type: "string" },
+  tree: { type: "boolean" },
+  treeDepth: { anyOf: [{ type: "string" }, { type: "number" }] },
+  includeUnparented: { type: "boolean" },
+  gcScope: {
+    type: "array",
+    items: { type: "string", enum: ["index", "embeddings", "runtime", "locks"] }
+  },
+  maxDepth: { anyOf: [{ type: "string" }, { type: "number" }] },
+  collapse: { type: "string", enum: ["none", "repeated"] },
+  summary: { type: "boolean" },
+  shell: { type: "string", enum: ["bash", "zsh", "fish"] },
+  stdin: { type: "boolean" },
+  file: { type: "string" },
+  preserveSourceIds: { type: "boolean" },
+  folder: { type: "string" },
+  subcommand: { type: "string" },
+  name: { type: "string" },
+  defaultStatus: { type: "string" },
+  alias: { type: "array", items: { type: "string" } },
+  role: { type: "array", items: { type: "string" } },
+  fieldType: { type: "string", enum: ["string", "number", "boolean", "string_array"] },
+  commands: { type: "array", items: { type: "string" } },
+  cliFlag: { type: "string" },
+  required: { type: "boolean" },
+  requiredOnCreate: { type: "boolean" },
+  allowUnset: { type: "boolean" },
+  requiredTypes: { type: "array", items: { type: "string" } },
+  infer: { type: "boolean" },
+  minCount: { type: "number" },
+  text: { type: "string" },
+  add: { type: "array", items: { type: "string" } },
+  addGlob: { type: "array", items: { type: "string" } },
+  remove: { type: "array", items: { type: "string" } },
+  migrate: { type: "array", items: { type: "string" } },
+  discover: { type: "boolean" },
+  apply: { type: "boolean" },
+  discoveryNote: { type: "string" },
+  // GH-170 (pm-pfnx): single-string note for files/docs add batches (the shared
+  // `note` key below is the array-typed create/update note seed).
+  addNote: { type: "string" },
+  list: { type: "boolean" },
+  appendStable: { type: "boolean" },
+  validatePaths: { type: "boolean" },
+  audit: { type: "boolean" },
+  dep: { type: "array", items: { type: "string" } },
+  depRemove: { type: "array", items: { type: "string" } },
+  replaceDeps: { type: "boolean" },
+  replaceTests: { type: "boolean" },
+  comment: { type: "array", items: { type: "string" } },
+  note: { type: "array", items: { type: "string" } },
+  learning: { type: "array", items: { type: "string" } },
+  linkedFile: { type: "array", items: { type: "string" } },
+  linkedTest: { type: "array", items: { type: "string" } },
+  doc: { type: "array", items: { type: "string" } },
+  reminder: { type: "array", items: { type: "string" } },
+  event: { type: "array", items: { type: "string" } },
+  typeOption: { type: "array", items: { type: "string" } },
+  field: { type: "array", items: { type: "string" } },
+  unset: { type: "array", items: { type: "string" } },
+  clearDeps: { type: "boolean" },
+  clearComments: { type: "boolean" },
+  clearNotes: { type: "boolean" },
+  clearLearnings: { type: "boolean" },
+  clearFiles: { type: "boolean" },
+  clearTests: { type: "boolean" },
+  clearDocs: { type: "boolean" },
+  clearReminders: { type: "boolean" },
+  clearEvents: { type: "boolean" },
+  clearTypeOptions: { type: "boolean" },
+  criterion: { type: "array", items: { type: "string" } },
+  clearCriteria: { type: "boolean" },
+  groupBy: { type: "string" },
+  completion: { type: "boolean" },
+  threshold: { anyOf: [{ type: "string" }, { type: "number" }] },
+  format: { type: "string" },
+  depth: { type: "string", enum: ["brief", "standard", "deep", "full"] },
+  section: { type: "array", items: { type: "string", enum: ["hierarchy", "activity", "progress", "blockers", "files", "workload", "staleness", "tests"] } },
+  activityLimit: { anyOf: [{ type: "string" }, { type: "number" }] },
+  staleThreshold: { type: "string" },
+  policy: { type: "string" }
+};
+var PLAN_SUBCOMMAND_VALUES = [
+  "create",
+  "show",
+  "add-step",
+  "update-step",
+  "complete-step",
+  "block-step",
+  "reorder-step",
+  "remove-step",
+  "link",
+  "unlink",
+  "decision",
+  "discovery",
+  "validation",
+  "resume",
+  "approve",
+  "materialize"
 ];
-function toUniqueFlagContracts(contracts) {
-  const seen = /* @__PURE__ */ new Set();
-  const unique = [];
-  for (const contract of contracts) {
-    const aliasKey = (contract.aliases ?? []).join(",");
-    const key = `${contract.flag}|${contract.short ?? ""}|${aliasKey}`;
-    if (seen.has(key)) {
-      continue;
-    }
-    seen.add(key);
-    unique.push(contract);
-  }
-  return unique;
-}
-function withSubcommandGlobalFlags(contracts) {
-  return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
-}
-var LIST_COMMAND_NAME_CONTRACTS = /* @__PURE__ */ new Set([
-  "list",
-  "list-all",
-  "list-draft",
-  "list-open",
-  "list-in-progress",
-  "list-blocked",
-  "list-closed",
-  "list-canceled"
-]);
-var NO_SURFACE_COMMAND_NAME_CONTRACTS = /* @__PURE__ */ new Set([
-  "reindex",
-  "help"
-]);
-function normalizeCommandNameForContracts(commandName) {
-  if (typeof commandName !== "string") {
-    return "";
-  }
-  return commandName.trim().toLowerCase();
-}
-function resolveSubcommandFlagContractsForCommand(commandName) {
-  const normalized = normalizeCommandNameForContracts(commandName);
-  if (normalized.length === 0) {
-    return withSubcommandGlobalFlags([]);
-  }
-  if (LIST_COMMAND_NAME_CONTRACTS.has(normalized)) {
-    return withSubcommandGlobalFlags(LIST_FILTER_FLAG_CONTRACTS);
-  }
-  if (NO_SURFACE_COMMAND_NAME_CONTRACTS.has(normalized)) {
-    return withSubcommandGlobalFlags([]);
-  }
-  if (normalized === "templates") {
-    return withSubcommandGlobalFlags(CREATE_FLAG_CONTRACTS);
-  }
-  if (normalized === "cal") {
-    return withSubcommandGlobalFlags(CALENDAR_FLAG_CONTRACTS);
-  }
-  if (normalized === "ctx") {
-    return withSubcommandGlobalFlags(CONTEXT_FLAG_CONTRACTS);
+var PLAN_ACTION_PARAMETER_PROPERTIES = {
+  subcommand: { type: "string", enum: [...PLAN_SUBCOMMAND_VALUES] },
+  stepRef: { type: "string" },
+  reorderTo: { anyOf: [{ type: "string" }, { type: "number" }] },
+  scope: { type: "string" },
+  harness: { type: "string", enum: [...PLAN_HARNESS_VALUES] },
+  mode: { type: "string", enum: [...PLAN_MODE_VALUES] },
+  resumeContext: { type: "string" },
+  related: { type: "string" },
+  blocks: { type: "string" },
+  claim: { type: "boolean" },
+  fromSearch: { type: "string" },
+  stepTitle: { type: "string" },
+  // pm-6mit: ordered step titles for create (string or array; values are never
+  // comma-split). On step subcommands a single value aliases stepTitle.
+  step: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
+  stepBody: { type: "string" },
+  stepOwner: { type: "string" },
+  stepStatus: { type: "string", enum: [...PLAN_STEP_STATUS_VALUES] },
+  stepEvidence: { type: "string" },
+  stepBlockedReason: { type: "string" },
+  stepReplacement: { type: "string" },
+  dependsOn: { type: "string" },
+  link: { type: "string" },
+  linkKind: { type: "string", enum: [...PLAN_STEP_LINK_KIND_VALUES] },
+  linkNote: { type: "string" },
+  promoteToItemDep: { type: "boolean" },
+  allowMultipleActive: { type: "boolean" },
+  file: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
+  test: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
+  doc: { anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }] },
+  decisionText: { type: "string" },
+  decision: { type: "string" },
+  decisionRationale: { type: "string" },
+  decisionEvidence: { type: "string" },
+  discoveryText: { type: "string" },
+  discovery: { type: "string" },
+  validationText: { type: "string" },
+  validation: { type: "string" },
+  validationCommand: { type: "string" },
+  validationExpected: { type: "string" },
+  steps: { type: "array", items: { type: "string" } },
+  materializeType: { type: "string" },
+  materializeParent: { type: "string" },
+  materializeTags: { type: "string" }
+};
+var PLAN_ACTION_PARAMETER_METADATA = {
+  subcommand: {
+    description: "Plan workflow operation to run.",
+    examples: ["create", "show", "add-step", "approve"]
+  },
+  stepRef: {
+    description: "Plan step id or order for step lifecycle subcommands.",
+    examples: ["plan-step-001", "1"]
+  },
+  reorderTo: {
+    description: "New integer order for reorder-step.",
+    examples: [1, "2"]
+  },
+  scope: {
+    description: "Short free-text scope statement describing what the Plan covers.",
+    examples: ["Release readiness audit", "Search package migration"]
+  },
+  mode: {
+    description: "Plan lifecycle mode.",
+    examples: ["draft", "research", "approved"]
+  },
+  step: {
+    description: "Ordered initial step titles for create (string or array, never comma-split; stepTitle, when also set, becomes the first step). For step subcommands a single value aliases stepTitle.",
+    examples: [["Read the code", "Write the fix", "Run the tests"]]
+  },
+  file: {
+    description: "File link to attach while creating or materializing a Plan.",
+    examples: ["path=src/cli.ts,note=implementation surface"]
+  },
+  test: {
+    description: "Test command link to attach while creating or materializing a Plan.",
+    examples: ["command=pnpm build,timeout_seconds=300"]
+  },
+  doc: {
+    description: "Documentation link to attach while creating or materializing a Plan.",
+    examples: ["path=docs/SDK.md,note=public API reference"]
   }
-  if (normalized === "test-runs-worker") {
-    return withSubcommandGlobalFlags(TEST_RUNS_FLAG_CONTRACTS);
+};
+var PM_TOOL_PARAMETER_METADATA = {
+  action: {
+    description: "Tool action to execute."
+  },
+  path: {
+    description: "Optional PM data root override for this invocation.",
+    examples: [".agents/pm"]
+  },
+  scope: {
+    description: "Scope selector for commands that operate on project or global state. Linked files, docs, and tests default to project scope when omitted.",
+    examples: ["project", "global"]
+  },
+  detail: {
+    description: "Detail mode for commands that support concise and deep diagnostics.",
+    examples: ["summary", "deep"]
+  },
+  trace: {
+    description: "When true for extension-doctor, include actionable registration traces in deep diagnostics."
+  },
+  reload: {
+    description: "When true for extension action payloads, trigger cache-busted extension module reload."
+  },
+  watch: {
+    description: "When true for extension-reload/extension action payloads, enable watch mode semantics."
+  },
+  runtimeProbe: {
+    description: "When true for extension-manage, run a doctor-like runtime activation probe for parity fields."
+  },
+  fixManagedState: {
+    description: "When true for extension-manage/extension-doctor, adopt unmanaged extensions before diagnostics/update checks."
+  },
+  target: {
+    description: "Positional target argument for the selected action (ID, source, package source, or extension name).",
+    examples: ["pm-a1b2", ".agents/pm/extensions/sample", "sample-extension"]
+  },
+  output: {
+    description: "File path for commands that write generated output, such as package/extension describe Markdown references.",
+    examples: ["docs/pm-package-reference.md"]
+  },
+  github: {
+    description: "GitHub shorthand owner/repo[/path] source for package/extension install actions.",
+    examples: ["org/repo/extensions/sample"]
+  },
+  ref: {
+    description: "Git ref/branch/tag used when installing from GitHub shorthand/URL sources.",
+    examples: ["main", "v1.0.0"]
+  },
+  cliOnly: {
+    description: "Restrict upgrade to the pm CLI/SDK npm package."
+  },
+  packagesOnly: {
+    description: "Restrict upgrade to managed installable pm packages."
+  },
+  repair: {
+    description: "Force npm global reinstall semantics when upgrading the pm CLI/SDK."
+  },
+  tag: {
+    description: "npm version or dist-tag used for CLI and registry package upgrades.",
+    examples: ["latest", "next", "2026.5.11"]
+  },
+  packageName: {
+    description: "Override the pm CLI package name for self-upgrade automation and tests.",
+    examples: ["@unbrained/pm-cli"]
+  },
+  json: {
+    description: "Emit machine-readable JSON output."
+  },
+  quiet: {
+    description: "Suppress stdout payload output."
+  },
+  noExtensions: {
+    description: "Disable extension loading for this invocation."
+  },
+  noPager: {
+    description: "Disable pager integration for help and long output."
+  },
+  profile: {
+    description: "Emit deterministic timing diagnostics to stderr."
+  },
+  timeoutMs: {
+    description: "Tool execution timeout in milliseconds.",
+    examples: [12e4]
+  },
+  id: {
+    description: "Item identifier for read or mutation actions.",
+    examples: ["pm-a1b2"]
+  },
+  runId: {
+    description: "Background test run identifier.",
+    examples: ["tr-kq9x3f-93acde"]
+  },
+  title: {
+    description: "Item title text."
+  },
+  description: {
+    description: "Item description text."
+  },
+  type: {
+    description: "Item type name from the active runtime type registry.",
+    examples: ["Task", "Feature"]
+  },
+  subcommand: {
+    description: "Subcommand selector for schema, profile, and telemetry actions."
+  },
+  name: {
+    description: "Custom item type name (schema add-type/remove-type/show), custom status id (schema show-status/add-status/remove-status), custom field key (schema add-field/remove-field/show-field), or profile name (profile show/apply/lint).",
+    examples: ["Spike", "review", "component"]
+  },
+  defaultStatus: {
+    description: "Default status hint recorded for a custom item type.",
+    examples: ["open"]
+  },
+  alias: {
+    description: "Aliases for the custom item type or status (repeatable).",
+    examples: [["spike", "research"]]
+  },
+  role: {
+    description: "Lifecycle roles for a custom status (schema add-status): draft, active, blocked, terminal, terminal_done, terminal_canceled, default_open, default_close, default_cancel.",
+    examples: [["active"], ["terminal", "terminal_done"]]
+  },
+  fieldType: {
+    description: "Value type for a custom field (schema add-field): string, number, boolean, or string_array.",
+    examples: ["string", "number", "string_array"]
+  },
+  commands: {
+    description: "Commands a custom field is wired onto (schema add-field): create, update, update_many, list, search, calendar, context.",
+    examples: [["create", "update"], ["create", "update", "list"]]
+  },
+  cliFlag: {
+    description: "Override the auto-derived CLI flag for a custom field (schema add-field).",
+    examples: ["--owner"]
+  },
+  required: {
+    description: "Mark a custom field as always required (schema add-field)."
+  },
+  requiredOnCreate: {
+    description: "Mark a custom field as required at create time (schema add-field)."
+  },
+  allowUnset: {
+    description: "Whether a custom field may be cleared via --unset (schema add-field); defaults to true."
+  },
+  requiredTypes: {
+    description: "Restrict a custom field's requirement to specific item types (schema add-field).",
+    examples: [["Bug"], ["Story", "Spike"]]
+  },
+  infer: {
+    description: "Infer custom item types from title-prefix conventions (schema add-type); previews unless apply is true."
+  },
+  minCount: {
+    description: "Minimum number of items sharing a title prefix for schema add-type inference (default 10).",
+    examples: [10, 25]
+  },
+  preset: {
+    description: "Governance preset for initialization flows.",
+    examples: ["minimal", "default", "strict"]
+  },
+  typePreset: {
+    description: "Domain item-type preset registered during initialization.",
+    examples: ["agile", "ops", "research"]
+  },
+  defaults: {
+    description: "Use non-interactive setup defaults during initialization."
+  },
+  verbose: {
+    description: "Include the full resolved settings tree in init output."
+  },
+  agentGuidance: {
+    description: "Control AGENTS.md/CLAUDE.md guidance behavior during init: ask, add, skip, or status.",
+    examples: ["ask", "add", "skip", "status"]
+  },
+  withPackages: {
+    description: "Install all bundled first-party pm packages during initialization."
+  },
+  createMode: {
+    description: "Create required-option policy mode.",
+    examples: ["strict", "progressive"]
+  },
+  schedulePreset: {
+    description: "Schedule-centric create preset for Reminder, Meeting, and Event types.",
+    examples: ["lightweight"]
+  },
+  status: {
+    description: "Item status value. Statuses are project-configurable via .agents/pm/settings.json (schema block); the built-in defaults are draft, open, in_progress, blocked, closed, canceled. Custom statuses defined for the project are accepted \u2014 discover the active set with the pm_contracts tool (workspace.statuses) or `pm contracts`. Unknown statuses are rejected at runtime with a did-you-mean hint rather than blocked by a fixed schema enum.",
+    examples: ["open", "in_progress"]
+  },
+  priority: {
+    description: "Priority value in range 0..4.",
+    examples: [0, 1, "2"]
+  },
+  order: {
+    description: "Planning order/rank value for create/update, or sort direction (asc|desc) for list-family sorting.",
+    examples: [0, 1, "2", "asc", "desc"]
+  },
+  sort: {
+    description: "List-family sort field selector.",
+    examples: ["priority", "deadline", "updated_at", "created_at", "title", "parent"]
+  },
+  tags: {
+    description: "Comma-delimited tag list.",
+    examples: ["pm-cli,agent-ux"]
+  },
+  addTags: {
+    description: "Tags to add to the existing list without replacing it. Each entry may be CSV or a JSON array.",
+    examples: [["agent-ux"], ["fix", "security"]]
+  },
+  removeTags: {
+    description: "Tags to remove from the existing list. Each entry may be CSV or a JSON array.",
+    examples: [["stale"], ["legacy", "wontfix"]]
+  },
+  deadline: {
+    description: "ISO/date timestamp or relative offset (+6h/+1d/+2w/+6m).",
+    examples: ["2026-04-01T00:00:00.000Z", "+1d"]
+  },
+  reminder: {
+    description: "Repeatable reminder seed entries at=<iso|relative>,text=<text>.",
+    examples: [["at=+2d,text=Review PR"]]
+  },
+  event: {
+    description: "Repeatable event seed entries start=<iso|relative> with end=<iso|relative> or duration=<relative|30min|PT30M>. Bare `m` remains months for backward compatibility.",
+    examples: [
+      ["start=2026-07-01T10:00:00Z,duration=2h,title=planning"],
+      ["start=2026-07-01T10:00:00Z,duration=30min,title=standup"],
+      ["start=2026-07-01T10:00:00Z,duration=PT30M,title=window"]
+    ]
+  },
+  estimate: {
+    description: "Estimated effort in minutes.",
+    examples: [60, "120"]
+  },
+  acceptanceCriteria: {
+    description: "Acceptance criteria text."
+  },
+  author: {
+    description: "Mutation author identity.",
+    examples: ["codex-agent"]
+  },
+  message: {
+    description: "History message for mutation audit trail."
+  },
+  assignee: {
+    description: "Assignee identity.",
+    examples: ["codex-agent"]
+  },
+  assigneeFilter: {
+    description: "Assignee presence selector for list/calendar/context/comments-audit filters.",
+    examples: ["assigned", "unassigned"]
+  },
+  parent: {
+    description: "Parent item ID filter for hierarchical list queries.",
+    examples: ["pm-epic01"]
+  },
+  blockedLimit: {
+    description: "Cap blocked rows returned by the next action (defaults to the ready --limit).",
+    examples: ["3"]
+  },
+  readyOnly: {
+    description: "When true, the next action omits the blocked companion list."
+  },
+  unset: {
+    description: "Repeatable list of front-matter fields to clear explicitly during create/update mutations.",
+    examples: [["deadline", "assignee"], ["close-reason"]]
+  },
+  clearDeps: {
+    description: "When true, clear linked dependencies."
+  },
+  replaceDeps: {
+    description: "When true for update, atomically replace dependencies with the supplied --dep values."
+  },
+  replaceTests: {
+    description: "When true for update, atomically replace linked tests with the supplied --test values."
+  },
+  clearComments: {
+    description: "When true, clear item comments."
+  },
+  clearNotes: {
+    description: "When true, clear item notes."
+  },
+  clearLearnings: {
+    description: "When true, clear item learnings."
+  },
+  clearFiles: {
+    description: "When true, clear linked files."
+  },
+  clearTests: {
+    description: "When true, clear linked tests."
+  },
+  clearDocs: {
+    description: "When true, clear linked docs."
+  },
+  clearReminders: {
+    description: "When true, clear reminders."
+  },
+  clearEvents: {
+    description: "When true, clear events."
+  },
+  clearTypeOptions: {
+    description: "When true, clear type option metadata."
+  },
+  clearCriteria: {
+    description: "When true for config set criteria-list keys (definition-of-done, metadata-required-fields, lifecycle pattern lists), clear the criteria list."
+  },
+  mode: {
+    description: "Mode selector for search/reindex (keyword|semantic|hybrid) and dedupe-audit (title_exact|title_fuzzy|parent_scope).",
+    examples: ["keyword", "hybrid", "title_exact"]
+  },
+  semanticWeight: {
+    description: "Per-query hybrid semantic weight override in [0,1] for search action; invalid values fall back to settings.",
+    examples: [0.2, "0.7"]
+  },
+  op: {
+    description: "History operation filter for activity output.",
+    examples: ["create", "update", "close", "update_audit"]
+  },
+  fullPeriod: {
+    description: "For day/week/month calendar views, include the full anchored period instead of clipping the start to now."
+  },
+  progress: {
+    description: "Emit progress diagnostics to stderr for long-running operations."
+  },
+  background: {
+    description: "Run linked tests in managed background mode."
+  },
+  addJson: {
+    description: "Repeatable JSON object or array input for adding linked-test entries without CSV escaping loss.",
+    examples: [[`{"command":"node scripts/run-tests.mjs test -- tests/unit/output.spec.ts","timeout_seconds":240}`]]
+  },
+  match: {
+    description: "Run only linked tests whose command or path contains this case-insensitive substring.",
+    examples: ["output.spec.ts", "coverage"]
+  },
+  onlyIndex: {
+    description: "Run only the 1-based linked-test index from pm test <id> --list order.",
+    examples: [1, "2"]
+  },
+  onlyLast: {
+    description: "Run only the most recently added linked-test entry."
+  },
+  envSet: {
+    description: "Repeatable runtime environment KEY=VALUE overrides for linked-test execution.",
+    examples: [["PORT=0", "PLAYWRIGHT_HTML_OPEN=never"]]
+  },
+  envClear: {
+    description: "Repeatable runtime environment variable names to clear before linked-test execution.",
+    examples: [["PLAYWRIGHT_BASE_URL"]]
+  },
+  sharedHostSafe: {
+    description: "Apply additive shared-host-safe runtime defaults during linked-test execution."
+  },
+  pmContext: {
+    description: "PM linked-test context mode (schema keeps isolated tracker data; tracker seeds source tracker data; auto uses tracker for PM tracker-read linked commands).",
+    examples: ["schema", "tracker", "auto"]
+  },
+  overrideLinkedPmContext: {
+    description: "Force run-level --pm-context to override per-linked-test pm_context_mode metadata for all linked-test entries."
+  },
+  failOnContextMismatch: {
+    description: "Fail linked PM command runs when source and sandbox tracker item counts differ."
+  },
+  failOnSkipped: {
+    description: "Treat skipped linked tests as dependency-failed policy violations."
+  },
+  failOnEmptyTestRun: {
+    description: "Treat successful linked-test commands that report zero executed tests as failures."
+  },
+  requireAssertionsForPm: {
+    description: "Require assertion metadata for linked PM command test entries during run execution."
+  },
+  checkContext: {
+    description: "Run linked PM command context preflight diagnostics before command execution."
+  },
+  autoPmContext: {
+    description: "Auto-remediate PM tracker-read linked commands by routing those entries through tracker context regardless of linked-test pm_context_mode overrides."
+  },
+  dryRun: {
+    description: "Preview command effects without mutating storage artifacts."
+  },
+  all: {
+    description: "For history-repair action: scan every stream for drift and repair each drifted stream in one audited pass (mutually exclusive with id)."
+  },
+  clear: {
+    description: "For focus action: clear the session focused item instead of setting it (mutually exclusive with id)."
+  },
+  gcScope: {
+    description: "Repeatable gc scope selector values (index, embeddings, runtime, locks, checkpoints).",
+    examples: [["index", "embeddings"], ["runtime"], ["locks"], ["checkpoints"]]
+  },
+  storage: {
+    description: "For stats action: include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries) for compaction and storage planning."
+  },
+  fieldUtilization: {
+    description: "For stats action: include a field_utilization block reporting present/total/percent for content fields (notes, learnings, files, docs, tests, comments, deps, body, linked_command) across all items so under-documented dimensions are visible at a glance."
+  },
+  offset: {
+    description: "Number of matching rows to skip before limit is applied.",
+    examples: [0, 50, "100"]
+  },
+  before: {
+    description: "For history-compact, compact entries strictly before this boundary (version number or ISO timestamp). Single-id mode only.",
+    examples: ["5", "2026-06-01T00:00:00.000Z"]
+  },
+  allOver: {
+    description: "For history-compact bulk mode, compact every stream with more than N entries. When history.compact_policy is enabled and this is omitted, the policy's max_entries is used.",
+    examples: [200, "500"]
+  },
+  minEntries: {
+    description: "For history-compact bulk mode, skip streams with at most N entries as already-compact (default 3).",
+    examples: [3, "10"]
+  },
+  closed: {
+    description: "For history-compact bulk mode, compact only closed (terminal) items' history streams."
+  },
+  allStreams: {
+    description: "For history-compact bulk mode, compact every history stream regardless of lifecycle state."
+  },
+  limitItems: {
+    description: "Maximum number of filtered items to include in comments-audit output (alias: --limit).",
+    examples: [10, "25"]
+  },
+  fullHistory: {
+    description: "When true for comments-audit, export full per-item comment history rows; cannot be combined with latest."
+  },
+  latest: {
+    description: "Number of most recent comments to include per item in comments-audit output (use 0 for summary-only item rows).",
+    examples: [0, 1, "3"]
+  },
+  literal: {
+    description: "Repeatable literal matcher used by history-redact to scrub exact string values.",
+    examples: ["[redacted_path_prefix]/private/path"]
+  },
+  regex: {
+    description: "Repeatable regex matcher used by history-redact. Accepts either /pattern/flags or a raw pattern (global mode is auto-enabled).",
+    examples: ["/192\\\\.168\\\\.[0-9.]+/g", "token=[A-Za-z0-9_-]+"]
+  },
+  replacement: {
+    description: 'Replacement text used by history-redact (defaults to "[redacted]").',
+    examples: ["[scrubbed_path]"]
+  },
+  validateClose: {
+    description: 'Close-time metadata validation mode ("off", "warn", or "strict").',
+    examples: ["off", "warn", "strict"]
+  },
+  checkMetadata: {
+    description: "Run metadata completeness checks."
+  },
+  metadataProfile: {
+    description: "Select metadata validation profile for --check-metadata.",
+    examples: ["core", "strict", "custom"]
+  },
+  checkResolution: {
+    description: "Run closed-item resolution metadata checks."
+  },
+  checkLifecycle: {
+    description: "Run active-item lifecycle governance drift checks."
+  },
+  checkStaleBlockers: {
+    description: "Include stale blocker-pattern diagnostics in lifecycle checks."
+  },
+  dependencyCycleSeverity: {
+    description: "Set dependency-cycle warning policy for lifecycle checks.",
+    examples: ["off", "warn", "error"]
+  },
+  parentCycleSeverity: {
+    description: "Set parent-cycle warning policy for lifecycle checks.",
+    examples: ["off", "warn", "error"]
+  },
+  checkFiles: {
+    description: "Run linked-file and orphaned-file checks."
+  },
+  strictDirectories: {
+    description: "Treat optional item-type directories as required health failures."
+  },
+  checkOnly: {
+    description: "For health action, run read-only diagnostics without refreshing vectors."
+  },
+  checkTelemetry: {
+    description: "For health action, probe telemetry endpoint health and include network diagnostics."
+  },
+  noRefresh: {
+    description: "For health action, skip vector refresh while still running checks."
+  },
+  refreshVectors: {
+    description: "For health action, explicitly refresh stale vectors."
+  },
+  verboseStaleItems: {
+    description: "For health action, include full stale-item arrays in vectorization details."
+  },
+  skipVectors: {
+    description: "For health action, skip vectorization checks for a faster diagnostic run."
+  },
+  skipIntegrity: {
+    description: "For health action, skip item/history file integrity checks for a faster diagnostic run."
+  },
+  skipDrift: {
+    description: "For health action, skip history drift hash checks for a faster diagnostic run."
+  },
+  scanMode: {
+    description: "Select file candidate scan mode for --check-files.",
+    examples: ["default", "tracked-all", "tracked-all-strict"]
+  },
+  includePmInternals: {
+    description: "Include PM storage internals in tracked-all candidate scans."
+  },
+  verboseFileLists: {
+    description: "For validate action, include full file-path lists for --check-files details."
+  },
+  verboseDiagnostics: {
+    description: "For validate action, include full diagnostic ID lists instead of compact summaries."
+  },
+  strictExit: {
+    description: "Return non-zero exit when health/validate/extension-doctor warnings are present."
+  },
+  failOnWarn: {
+    description: "Alias for strictExit in health/validate/extension-doctor action payloads."
+  },
+  fixHints: {
+    description: "For validate action, add a machine-executable fix_hints[] of pm commands to each failing check's details."
+  },
+  autoFix: {
+    description: "For validate action, apply the safe, deterministic subset of fix-hint remediations (field backfills) automatically; combine with dryRun to preview and fixScope to grant gated scopes."
+  },
+  fixScope: {
+    description: "For validate action, grant --auto-fix scopes (metadata, resolution, estimates, lifecycle). Defaults to the safe scopes metadata and resolution; estimates (per-type default estimated_minutes backfill) and lifecycle must be named explicitly.",
+    examples: [["estimates"], ["lifecycle"], ["metadata", "resolution"]]
+  },
+  pruneMissing: {
+    description: "For validate action, remove stale linked-file/doc LINKS whose paths classified as deleted (link removal only \u2014 never touches real files); honors dryRun."
+  },
+  checkHistoryDrift: {
+    description: "Run item/history hash drift checks."
+  },
+  checkCommandReferences: {
+    description: "Run linked-command PM-ID reference checks."
+  },
+  allowAuditNote: {
+    description: "For notes action, allow non-owner append-only note audits without requiring --force."
+  },
+  allowAuditLearning: {
+    description: "For learnings action, allow non-owner append-only learning audits without requiring --force."
+  },
+  allowAuditComment: {
+    description: "For comments action, allow non-owner append-only comment audits without requiring --force."
+  },
+  edit: {
+    description: "For comments action, replace the comment at this 1-based index with the supplied replacement text (add/stdin/file)."
+  },
+  delete: {
+    description: "For comments action, delete the comment at this 1-based index."
+  },
+  stdin: {
+    description: "When true for comments action, read comment text from piped stdin (supports multiline markdown)."
+  },
+  file: {
+    description: "Path to input file for actions that read payload text, such as comments --file.",
+    examples: ["notes/comment.md"]
+  },
+  allowAuditUpdate: {
+    description: "Allow non-owner metadata-only update audits without requiring --force."
+  },
+  allowAuditDepUpdate: {
+    description: "Allow non-owner append-only dependency update audits without requiring --force."
+  },
+  allowAuditRelease: {
+    description: "Allow non-owner release handoffs that clear assignee metadata without requiring --force."
+  },
+  preserveSourceIds: {
+    description: "Preserve explicit source IDs during Beads imports instead of normalizing to tracker prefix.",
+    examples: [true]
+  },
+  appendStable: {
+    description: "When true for files action, preserve existing linked-file order and append new links without full-array resorting."
+  },
+  discover: {
+    description: "When true for files action, use `pm files discover <id>` to scan item text for referenced file paths."
+  },
+  apply: {
+    description: "Persist changes instead of returning a dry-run preview: for files discovery, add the missing discovered file links; for schema add-type --infer, register the inferred custom item types."
+  },
+  discoveryNote: {
+    description: "Note attached to file links added by files discovery.",
+    examples: ["discovered from item text"]
+  },
+  addNote: {
+    description: "Note attached to every link added by add/addGlob in this call (per-entry embedded note= wins; requires add or addGlob). Maps to the CLI --note flag on pm files/pm docs.",
+    examples: ["command wiring"]
+  },
+  list: {
+    description: "When true, list command-specific entries without mutating state (for example linked paths for files/docs or topics for guide).",
+    examples: [true]
+  },
+  stream: {
+    description: "Stream selector: test-runs logs accepts stdout|stderr|both; activity accepts boolean/rows|ndjson|jsonl for line-delimited output.",
+    examples: ["stderr", "stdout", "both", "rows", "ndjson", "jsonl", true]
+  },
+  tail: {
+    description: "Number of lines to tail for background run logs.",
+    examples: [100]
+  },
+  query: {
+    description: "Search query text for search action."
+  },
+  keywords: {
+    description: "Alias for query in search action payloads."
+  },
+  includeLinked: {
+    description: "Include readable linked docs/files/tests content in keyword and hybrid lexical scoring."
+  },
+  titleExact: {
+    description: "For search action, require exact normalized title match for the full query string."
+  },
+  phraseExact: {
+    description: "For search action, require exact normalized query phrase match in item text fields."
+  },
+  highlight: {
+    description: "For search action, emit per-field matched-text snippets (wrapped in \xAB\u2026\xBB) on each hit. Off by default."
+  },
+  includeBody: {
+    description: "When true for list-family actions, include item body text in projected rows."
+  },
+  noTruncate: {
+    description: "When true for list-family actions, return every matched row, overriding any limit (surfaces total when rows were dropped)."
+  },
+  compact: {
+    description: "Render compact projection output for search and list-family actions."
+  },
+  brief: {
+    description: "Emit compact low-token output for commands that support terse projections or health details.",
+    examples: [true]
+  },
+  full: {
+    description: "Enable command-specific full/detail output mode when supported, such as deep item reads for get or full payload mode for search/history."
+  },
+  fields: {
+    description: "Comma-separated projection fields for get, search, list-family, or context outputs. Valid field names are command-specific (e.g. score/matched_fields apply to search; context projects focus-row fields such as priority/deadline/completion_pct).",
+    examples: ["id,title,status,parent,type", "id,title,score,matched_fields", "id,title,priority,deadline"]
+  },
+  groupBy: {
+    description: "Comma-separated aggregate grouping fields (supported: parent,type,priority,status,assignee,tags,sprint,release).",
+    examples: ["parent,type", "type,status", "priority,assignee", "tags", "sprint,release"]
+  },
+  count: {
+    description: "Enable grouped count output for aggregate action."
+  },
+  completion: {
+    description: "For aggregate action, add open/in_progress/closed/other counts and completion_pct per group."
+  },
+  sum: {
+    description: "Numeric field to sum per aggregate group (count and null_count are still returned).",
+    examples: ["estimated_minutes", "priority"]
+  },
+  avg: {
+    description: "Numeric field to average per aggregate group (count and null_count are still returned).",
+    examples: ["estimated_minutes", "priority"]
+  },
+  tree: {
+    description: "When true for list/get actions, render recursive parent/child tree ordering."
+  },
+  treeDepth: {
+    description: "Maximum recursion depth for tree output (0 keeps root rows only).",
+    examples: [0, 1, "2"]
+  },
+  includeUnparented: {
+    description: "Include unparented rows when aggregate grouping includes parent."
+  },
+  maxDepth: {
+    description: "Maximum dependency traversal depth for deps action (0 keeps only the root node).",
+    examples: [0, 1, "2"]
+  },
+  collapse: {
+    description: 'Dependency tree collapse mode for deps action ("none" or "repeated").',
+    examples: ["none", "repeated"]
+  },
+  summary: {
+    description: "When true for deps action, return counts only without full tree/graph payloads."
+  },
+  threshold: {
+    description: "Dedupe-audit fuzzy title similarity threshold between 0 and 1.",
+    examples: [0.5, "0.75"]
+  },
+  shell: {
+    description: "Shell target for completion generation.",
+    examples: ["bash"]
+  },
+  eagerTags: {
+    description: "When true for completion, eagerly embed current tracker tags into generated scripts (legacy mode)."
+  },
+  contractAction: {
+    description: "Filter contracts schema to one tool action.",
+    examples: ["create", "update"]
+  },
+  command: {
+    description: "Scope contracts output to one CLI command name; action/schema surfaces narrow by default.",
+    examples: ["create", "search", "list"]
+  },
+  schemaOnly: {
+    description: "When true, contracts action returns schema-focused payloads (mutually exclusive with flagsOnly/availabilityOnly)."
+  },
+  flagsOnly: {
+    description: "When true, contracts action returns only command flag surface payloads (mutually exclusive projection mode)."
+  },
+  availabilityOnly: {
+    description: "When true, contracts action returns only action availability payloads (mutually exclusive projection mode)."
+  },
+  runtimeOnly: {
+    description: "When true, contracts action only includes actions invocable in the current runtime."
+  },
+  activeOnly: {
+    description: "Alias for runtimeOnly in contracts action payloads."
+  },
+  depth: {
+    description: "Context depth level controlling how many sections are included (brief=focus+agenda, standard=+hierarchy/activity/progress/workload, deep=all sections, full=every section with no per-section row cap).",
+    examples: ["brief", "standard", "deep", "full"]
+  },
+  section: {
+    description: "Repeatable section selector for context; overrides --depth when provided.",
+    examples: [["hierarchy", "activity"], ["blockers", "files", "staleness"]]
+  },
+  activityLimit: {
+    description: "Maximum number of recent activity entries to include in context output.",
+    examples: [5, 10, "20"]
+  },
+  staleThreshold: {
+    description: "Staleness cutoff in days for context staleness section (e.g. 7 or 7d).",
+    examples: ["7", "14d", "30"]
   }
-  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 "describe":
-        return withSubcommandGlobalFlags(EXTENSION_DESCRIBE_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([]);
+};
+var PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
+  schema: {
+    name: {
+      description: "Custom item type name (add-type/remove-type/show), custom status id (show-status/add-status/remove-status), or custom field key (add-field/remove-field/show-field). Required for those subcommands.",
+      examples: ["Spike", "review", "component"]
+    }
+  },
+  profile: {
+    name: {
+      description: "Profile name for show/apply/lint. Built-in profiles are agile, ops, and research; an active extension can contribute additional archetype names that resolve here too.",
+      examples: ["agile", "ops", "research"]
     }
   }
-  switch (normalized) {
-    case "init":
-      return withSubcommandGlobalFlags(INIT_FLAG_CONTRACTS);
-    case "config":
-      return withSubcommandGlobalFlags(CONFIG_FLAG_CONTRACTS);
-    case "extension":
-    case "package":
-    case "packages":
-      return withSubcommandGlobalFlags(EXTENSION_FLAG_CONTRACTS);
-    case "install":
-      return withSubcommandGlobalFlags(INSTALL_FLAG_CONTRACTS);
-    case "upgrade":
-      return withSubcommandGlobalFlags(UPGRADE_FLAG_CONTRACTS);
-    case "create":
-      return withSubcommandGlobalFlags(CREATE_FLAG_CONTRACTS);
-    case "copy":
-      return withSubcommandGlobalFlags(COPY_FLAG_CONTRACTS);
-    case "focus":
-      return withSubcommandGlobalFlags(FOCUS_FLAG_CONTRACTS);
-    case "aggregate":
-      return withSubcommandGlobalFlags(AGGREGATE_FLAG_CONTRACTS);
-    case "calendar":
-      return withSubcommandGlobalFlags(CALENDAR_FLAG_CONTRACTS);
-    case "context":
-      return withSubcommandGlobalFlags(CONTEXT_FLAG_CONTRACTS);
-    case "get":
-      return withSubcommandGlobalFlags(GET_FLAG_CONTRACTS);
-    case "search":
-      return withSubcommandGlobalFlags(SEARCH_FLAG_CONTRACTS);
-    case "eval":
-      return withSubcommandGlobalFlags(EVAL_FLAG_CONTRACTS);
-    case "history":
-      return withSubcommandGlobalFlags(HISTORY_FLAG_CONTRACTS);
-    case "history-redact":
-      return withSubcommandGlobalFlags(HISTORY_REDACT_FLAG_CONTRACTS);
-    case "history-repair":
-      return withSubcommandGlobalFlags(HISTORY_REPAIR_FLAG_CONTRACTS);
-    case "history-compact":
-      return withSubcommandGlobalFlags(HISTORY_COMPACT_FLAG_CONTRACTS);
-    case "schema":
-      return withSubcommandGlobalFlags(SCHEMA_FLAG_CONTRACTS);
-    case "plan":
-      return withSubcommandGlobalFlags(PLAN_FLAG_CONTRACTS);
-    case "activity":
-      return withSubcommandGlobalFlags(ACTIVITY_FLAG_CONTRACTS);
-    case "restore":
-      return withSubcommandGlobalFlags(RESTORE_FLAG_CONTRACTS);
-    case "update":
-      return withSubcommandGlobalFlags(UPDATE_FLAG_CONTRACTS);
-    case "update-many":
-      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":
-      return withSubcommandGlobalFlags(APPEND_FLAG_CONTRACTS);
-    case "comments":
-      return withSubcommandGlobalFlags(COMMENTS_FLAG_CONTRACTS);
-    case "notes":
-      return withSubcommandGlobalFlags(NOTES_FLAG_CONTRACTS);
-    case "learnings":
-      return withSubcommandGlobalFlags(LEARNINGS_FLAG_CONTRACTS);
-    case "files":
-      return withSubcommandGlobalFlags(FILES_FLAG_CONTRACTS);
-    case "docs":
-      return withSubcommandGlobalFlags(DOCS_FLAG_CONTRACTS);
-    case "deps":
-      return withSubcommandGlobalFlags(DEPS_FLAG_CONTRACTS);
-    case "test":
-      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":
-      return withSubcommandGlobalFlags(CLAIM_FLAG_CONTRACTS);
-    case "release":
-      return withSubcommandGlobalFlags(RELEASE_FLAG_CONTRACTS);
-    case "start-task":
-      return withSubcommandGlobalFlags(START_TASK_FLAG_CONTRACTS);
-    case "pause-task":
-      return withSubcommandGlobalFlags(PAUSE_TASK_FLAG_CONTRACTS);
-    case "close-task":
-      return withSubcommandGlobalFlags(CLOSE_TASK_FLAG_CONTRACTS);
-    case "meet":
-      return withSubcommandGlobalFlags(MEET_FLAG_CONTRACTS);
-    case "event":
-      return withSubcommandGlobalFlags(EVENT_FLAG_CONTRACTS);
-    case "remind":
-      return withSubcommandGlobalFlags(REMIND_FLAG_CONTRACTS);
-    default:
-      return withSubcommandGlobalFlags([]);
-  }
-}
+};
+
+// dist/sdk/cli-contracts/tool-schema.js
 var PM_TOOL_GLOBAL_PARAMETER_KEYS = [
   "json",
   "quiet",
@@ -3947,6 +3906,20 @@ var SEARCH_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
   "full",
   ...TOOL_SEARCH_FILTER_OPTION_CONTRACTS.map((entry) => entry.param)
 ]);
+var NEXT_CONTRACT_PARAMETER_KEYS = toSchemaKeyList([
+  "type",
+  "tag",
+  "priority",
+  "assignee",
+  "assigneeFilter",
+  "sprint",
+  "release",
+  "parent",
+  "limit",
+  "blockedLimit",
+  "readyOnly",
+  "format"
+]);
 var AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS = ["author", "message", "force"];
 var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
   init: { optional: ["prefix", "preset", "typePreset", "defaults", "author", "agentGuidance", "withPackages", "force", "verbose"] },
@@ -3962,7 +3935,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
   "extension-uninstall": { required: ["target"], optional: ["scope"] },
   "extension-explore": { optional: ["scope"] },
   "extension-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
-  "extension-describe": { optional: ["target", "scope"] },
+  "extension-describe": { optional: ["target", "scope", "markdown", "output"] },
   "extension-reload": { optional: ["scope", "watch"] },
   "extension-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
   "extension-catalog": { optional: ["scope", "fields"] },
@@ -3982,6 +3955,8 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "explore",
       "manage",
       "describe",
+      "markdown",
+      "output",
       "reload",
       "doctor",
       "catalog",
@@ -4006,7 +3981,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
   "package-uninstall": { required: ["target"], optional: ["scope"] },
   "package-explore": { optional: ["scope"] },
   "package-manage": { optional: ["scope", "runtimeProbe", "fixManagedState"] },
-  "package-describe": { optional: ["target", "scope"] },
+  "package-describe": { optional: ["target", "scope", "markdown", "output"] },
   "package-reload": { optional: ["scope", "watch"] },
   "package-doctor": { optional: ["scope", "detail", "trace", "fixManagedState", "strictExit", "failOnWarn"] },
   "package-catalog": { optional: ["scope", "fields"] },
@@ -4026,6 +4001,8 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "explore",
       "manage",
       "describe",
+      "markdown",
+      "output",
       "reload",
       "doctor",
       "catalog",
@@ -4065,7 +4042,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
   "list-canceled": { optional: LIST_CONTRACT_PARAMETER_KEYS },
   aggregate: { optional: AGGREGATE_CONTRACT_PARAMETER_KEYS },
   "dedupe-audit": { optional: DEDUPE_AUDIT_CONTRACT_PARAMETER_KEYS },
-  guide: { optional: ["format", "depth"] },
+  guide: { optional: ["list", "format", "depth"] },
   context: { optional: CONTEXT_CONTRACT_PARAMETER_KEYS },
   ctx: { optional: CONTEXT_CONTRACT_PARAMETER_KEYS },
   get: { required: ["id"], optional: ["depth", "full", "fields", "tree", "treeDepth", "format"] },
@@ -4073,6 +4050,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     optional: SEARCH_CONTRACT_PARAMETER_KEYS,
     anyOfRequired: [["query"], ["keywords"]]
   },
+  next: { optional: NEXT_CONTRACT_PARAMETER_KEYS },
   reindex: { optional: ["mode", "progress"] },
   history: { required: ["id"], optional: ["limit", "compact", "full", "diff", "verify", "format"] },
   "history-redact": {
@@ -4134,6 +4112,16 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       { property: "subcommand", value: "apply-preset", required: ["typePreset"] }
     ]
   },
+  profile: {
+    required: ["subcommand"],
+    // No --message: profile staging writes config/schema files, not item history.
+    optional: ["name", "dryRun", "author", "force"],
+    conditionalRequired: [
+      { property: "subcommand", value: "show", required: ["name"] },
+      { property: "subcommand", value: "apply", required: ["name"] },
+      { property: "subcommand", value: "lint", required: ["name"] }
+    ]
+  },
   plan: {
     required: ["subcommand"],
     optional: [
@@ -4196,7 +4184,20 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
   update: { required: ["id"], optional: UPDATE_CONTRACT_PARAMETER_KEYS },
   "update-many": { optional: UPDATE_MANY_CONTRACT_PARAMETER_KEYS },
   normalize: { optional: NORMALIZE_CONTRACT_PARAMETER_KEYS },
-  close: { required: ["id"], optional: ["text", "duplicateOf", "validateClose", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
+  close: {
+    required: ["id"],
+    optional: [
+      "text",
+      "reason",
+      "closeReason",
+      "duplicateOf",
+      "validateClose",
+      "resolution",
+      "expectedResult",
+      "actualResult",
+      ...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 },
@@ -4236,6 +4237,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "addGlob",
       "remove",
       "migrate",
+      "list",
       // GH-170 (pm-pfnx): `addNote` is the MCP spelling of the CLI --note flag
       // (the shared `note` parameter is the array-typed create/update note
       // seed, so files/docs use a distinct single-string key).
@@ -4346,6 +4348,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "noRefresh",
       "refreshVectors",
       "verboseStaleItems",
+      "brief",
       "summary",
       "skipVectors",
       "skipIntegrity",
@@ -4361,6 +4364,7 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
       "checkLifecycle",
       "checkStaleBlockers",
       "dependencyCycleSeverity",
+      "parentCycleSeverity",
       "checkFiles",
       "scanMode",
       "includePmInternals",
@@ -4379,13 +4383,13 @@ var PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
     ]
   },
   gc: { optional: ["dryRun", "gcScope"] },
-  contracts: { optional: ["contractAction", "command", "schemaOnly", "flagsOnly", "availabilityOnly", "runtimeOnly", "activeOnly"] },
+  contracts: { optional: ["contractAction", "command", "schemaOnly", "flagsOnly", "availabilityOnly", "runtimeOnly", "activeOnly", "full"] },
   completion: { required: ["shell"], optional: ["eagerTags"] },
   claim: { required: ["id"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
   release: { required: ["id"], optional: ["allowAuditRelease", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] },
   "start-task": { required: ["id"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
   "pause-task": { required: ["id"], optional: AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS },
-  "close-task": { required: ["id"], optional: ["text", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] }
+  "close-task": { required: ["id"], optional: ["text", "validateClose", ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS] }
 };
 var PM_TOOL_ACTION_PARAMETER_CONTRACTS = Object.freeze(Object.fromEntries(PM_TOOL_ACTIONS.map((action) => [action, PM_TOOL_ACTION_SCHEMA_CONTRACTS[action]])));
 function fallbackToolParameterDescription(key) {
@@ -4404,6 +4408,10 @@ function actionScopedToolParameterMetadata(action, key) {
   if (action === "plan" && Object.prototype.hasOwnProperty.call(PLAN_ACTION_PARAMETER_METADATA, key)) {
     return PLAN_ACTION_PARAMETER_METADATA[key];
   }
+  const actionOverrides = PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA[action];
+  if (actionOverrides && Object.prototype.hasOwnProperty.call(actionOverrides, key)) {
+    return actionOverrides[key];
+  }
   return PM_TOOL_PARAMETER_METADATA[key];
 }
 function decorateActionScopedToolParameterDefinition(action, key, definition) {
@@ -4424,12 +4432,7 @@ function actionScopedToolParameterDefinition(action, key) {
   }
   return PM_TOOL_PARAMETER_PROPERTIES[key];
 }
-function buildActionScopedToolSchema(action) {
-  const contract = PM_TOOL_ACTION_SCHEMA_CONTRACTS[action];
-  const required = toSchemaKeyList(contract.required ?? []);
-  const optional = toSchemaKeyList(contract.optional ?? []);
-  const mutationParameterKeys = PM_TOOL_ACTION_MUTATION_PARAMETER_KEYS[action] ?? [];
-  const allowedKeys = toSchemaKeyList(["action", ...PM_TOOL_GLOBAL_PARAMETER_KEYS, ...mutationParameterKeys, ...required, ...optional]);
+function buildActionScopedSchemaProperties(action, allowedKeys) {
   const properties = {
     action: {
       const: action,
@@ -4445,48 +4448,42 @@ function buildActionScopedToolSchema(action) {
       properties[key] = decorateActionScopedToolParameterDefinition(action, key, definition);
     }
   }
-  const schema = {
-    type: "object",
-    additionalProperties: false,
-    required: ["action", ...required],
-    title: `pm action "${action}" parameters`,
-    properties
-  };
-  if (contract.anyOfRequired && contract.anyOfRequired.length > 0) {
-    schema.anyOf = contract.anyOfRequired.map((requiredFields) => ({
-      required: [...requiredFields]
-    }));
-  }
-  const oneOfRequiredGroups = contract.oneOfRequired;
-  if (oneOfRequiredGroups && oneOfRequiredGroups.length > 0) {
-    const allOneOfFields = oneOfRequiredGroups.flat();
-    schema.oneOf = oneOfRequiredGroups.map((requiredFields) => {
-      const otherFields = allOneOfFields.filter((field) => !requiredFields.includes(field));
-      return {
-        required: [...requiredFields],
-        ...otherFields.length > 0 ? { not: { anyOf: otherFields.map((field) => ({ required: [field] })) } } : {},
-        ...action === "history-repair" && requiredFields.includes("all") ? { properties: { all: { const: true } } } : {}
-      };
-    });
-  }
+  return properties;
+}
+function buildOneOfSchemaEntries(action, oneOfRequiredGroups) {
+  const allOneOfFields = oneOfRequiredGroups.flat();
+  return oneOfRequiredGroups.map((requiredFields) => {
+    const otherFields = allOneOfFields.filter((field) => !requiredFields.includes(field));
+    return {
+      required: [...requiredFields],
+      ...otherFields.length > 0 ? { not: { anyOf: otherFields.map((field) => ({ required: [field] })) } } : {},
+      ...action === "history-repair" && requiredFields.includes("all") ? { properties: { all: { const: true } } } : {}
+    };
+  });
+}
+function buildActionScopedAllOf(contract) {
+  const allOf = [];
   if (contract.conditionalRequired && contract.conditionalRequired.length > 0) {
-    schema.allOf = contract.conditionalRequired.map((entry) => ({
-      if: {
-        properties: {
-          [entry.property]: { const: entry.value }
+    for (const entry of contract.conditionalRequired) {
+      allOf.push({
+        if: {
+          properties: {
+            [entry.property]: { const: entry.value }
+          },
+          required: [entry.property]
         },
-        required: [entry.property]
-      },
-      then: {
-        required: entry.required
-      }
-    }));
+        // eslint-disable-next-line unicorn/no-thenable -- JSON Schema conditional keyword, not a Promise-like object.
+        then: {
+          required: entry.required
+        }
+      });
+    }
   }
   if (contract.dependentAnyOfRequired && contract.dependentAnyOfRequired.length > 0) {
-    const allOf = Array.isArray(schema.allOf) ? [...schema.allOf] : [];
     for (const entry of contract.dependentAnyOfRequired) {
       allOf.push({
         if: { required: [entry.property] },
+        // eslint-disable-next-line unicorn/no-thenable -- JSON Schema conditional keyword, not a Promise-like object.
         then: {
           anyOf: entry.anyOfRequired.map((requiredFields) => ({
             required: [...requiredFields]
@@ -4494,13 +4491,37 @@ function buildActionScopedToolSchema(action) {
         }
       });
     }
-    schema.allOf = allOf;
   }
   if (contract.mutuallyExclusive && contract.mutuallyExclusive.length > 0) {
-    const allOf = Array.isArray(schema.allOf) ? [...schema.allOf] : [];
     for (const group of contract.mutuallyExclusive) {
       allOf.push({ not: { required: toSchemaKeyList(group) } });
     }
+  }
+  return allOf;
+}
+function buildActionScopedToolSchema(action) {
+  const contract = PM_TOOL_ACTION_SCHEMA_CONTRACTS[action];
+  const required = toSchemaKeyList(contract.required ?? []);
+  const optional = toSchemaKeyList(contract.optional ?? []);
+  const mutationParameterKeys = PM_TOOL_ACTION_MUTATION_PARAMETER_KEYS[action] ?? [];
+  const allowedKeys = toSchemaKeyList(["action", ...PM_TOOL_GLOBAL_PARAMETER_KEYS, ...mutationParameterKeys, ...required, ...optional]);
+  const schema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["action", ...required],
+    title: `pm action "${action}" parameters`,
+    properties: buildActionScopedSchemaProperties(action, allowedKeys)
+  };
+  if (contract.anyOfRequired && contract.anyOfRequired.length > 0) {
+    schema.anyOf = contract.anyOfRequired.map((requiredFields) => ({
+      required: [...requiredFields]
+    }));
+  }
+  if (contract.oneOfRequired && contract.oneOfRequired.length > 0) {
+    schema.oneOf = buildOneOfSchemaEntries(action, contract.oneOfRequired);
+  }
+  const allOf = buildActionScopedAllOf(contract);
+  if (allOf.length > 0) {
     schema.allOf = allOf;
   }
   return schema;
@@ -4521,7 +4542,7 @@ function createLazyContractSchema(build) {
     }
   });
 }
-var PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.0.3";
+var PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.0.6";
 var PM_TOOL_PARAMETERS_SCHEMA_MAJOR = PM_TOOL_PARAMETERS_SCHEMA_VERSION.split(".")[0];
 var PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION = "1.0.0";
 var PM_TOOL_PARAMETERS_SCHEMA = createLazyContractSchema(() => ({
@@ -4542,8 +4563,8 @@ function toProviderCompatibleParameterDefinition(key, definition) {
   if (firstTypedVariant) {
     const { anyOf: _anyOf2, ...rest2 } = decorated;
     return {
-      ...rest2,
-      type: firstTypedVariant.type
+      ...firstTypedVariant,
+      ...rest2
     };
   }
   const { anyOf: _anyOf, ...rest } = decorated;
@@ -4583,6 +4604,7 @@ export {
   SEARCH_COMMANDER_STRING_OPTION_CONTRACTS,
   CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS,
   CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS,
+  NEXT_COMMANDER_STRING_OPTION_CONTRACTS,
   ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS,
   readFirstStringFromCommanderOptions,
   readFirstValueFromCommanderOptions,
@@ -4618,11 +4640,14 @@ export {
   HISTORY_REPAIR_FLAG_CONTRACTS,
   HISTORY_COMPACT_FLAG_CONTRACTS,
   SCHEMA_FLAG_CONTRACTS,
+  PROFILE_FLAG_CONTRACTS,
   PLAN_FLAG_CONTRACTS,
   INIT_FLAG_CONTRACTS,
   CONFIG_FLAG_CONTRACTS,
   EXTENSION_FLAG_CONTRACTS,
   EXTENSION_INIT_FLAG_CONTRACTS,
+  PACKAGE_FLAG_CONTRACTS,
+  PACKAGE_INIT_FLAG_CONTRACTS,
   EXTENSION_INSTALL_FLAG_CONTRACTS,
   EXTENSION_UNINSTALL_FLAG_CONTRACTS,
   EXTENSION_EXPLORE_FLAG_CONTRACTS,
@@ -4667,12 +4692,13 @@ export {
   GUIDE_FLAG_CONTRACTS,
   DEPS_FLAG_CONTRACTS,
   EVAL_FLAG_CONTRACTS,
+  NEXT_FLAG_CONTRACTS,
   SEARCH_FLAG_CONTRACTS,
   CONTRACTS_FLAG_CONTRACTS,
   COMPLETION_FLAG_CONTRACTS,
   resolveSubcommandFlagContractsForCommand,
   PM_TOOL_PARAMETERS_SCHEMA
 };
-//# sourceMappingURL=chunk-OF7V47P3.js.map
+//# sourceMappingURL=chunk-HXTQJXWT.js.map
 
-//# debugId=358fc257-d2e2-5538-b106-a600db4ae795
+//# debugId=43af9766-fa42-5af2-8e94-459bc0205f26