@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Enum Contracts.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d05ce92b-bee8-5cce-afc2-8c7901306a30")}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]="8b8b6b8e-5061-5da4-a369-eca379c0090b")}catch(e){}}();
 import { KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_SERVICE_NAMES, KNOWN_EXTENSION_TRUST_MODES, } from "../../core/extensions/extension-types.js";
 import { PM_COMMAND_ALIAS_CONTRACTS } from "./command-aliases.js";
 /** Public contract for pm extension capability contracts, shared by SDK and presentation-layer consumers. */
@@ -140,10 +140,11 @@ export const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS = [
     "activate",
     "deactivate",
 ];
+/** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
+export const PM_ITEM_ACTION_SUBCOMMANDS = ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
 export const PM_CLI_ONLY_TOOL_ACTION_WAIVERS = {
     help: "Commander help rendering has no SDK operation result.",
-    item: "The item namespace only groups lifecycle subcommands already exposed as actions.",
     packages: "The plural package alias only renders package-oriented help.",
 };
 /**
@@ -159,6 +160,9 @@ export const PM_TOOL_ACTIONS = Object.freeze(PM_CORE_COMMAND_NAMES.flatMap((comm
             command,
         ];
     }
+    if (command === "item") {
+        return PM_ITEM_ACTION_SUBCOMMANDS.map((subcommand) => `item-${subcommand}`);
+    }
     return [command];
 }));
 /** Deprecated compatibility actions accepted by the SDK but omitted from canonical MCP discovery. */
@@ -172,9 +176,15 @@ export function analyzePmToolActionParity(cliCommands = PM_CORE_COMMAND_NAMES, t
     const toolActionSet = new Set(toolActions);
     const cliCommandSet = new Set(cliCommands);
     return {
-        missing_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) && waivers[command] === undefined),
-        waived_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) && waivers[command] !== undefined),
-        stale_waivers: Object.keys(waivers).filter((command) => !cliCommandSet.has(command) || toolActionSet.has(command)),
+        missing_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) &&
+            !toolActions.some((action) => action.startsWith(`${command}-`)) &&
+            waivers[command] === undefined),
+        waived_cli_actions: cliCommands.filter((command) => !toolActionSet.has(command) &&
+            !toolActions.some((action) => action.startsWith(`${command}-`)) &&
+            waivers[command] !== undefined),
+        stale_waivers: Object.keys(waivers).filter((command) => !cliCommandSet.has(command) ||
+            toolActionSet.has(command) ||
+            toolActions.some((action) => action.startsWith(`${command}-`))),
     };
 }
 /** Implements check whether pm tool action for the public runtime surface of this module. */
@@ -198,4 +208,4 @@ export function isPmExtensionPolicySurfaceContract(value) {
     return PM_EXTENSION_POLICY_SURFACE_CONTRACTS.includes(value);
 }
 //# sourceMappingURL=enum-contracts.js.map
-//# debugId=d05ce92b-bee8-5cce-afc2-8c7901306a30
+//# debugId=8b8b6b8e-5061-5da4-a369-eca379c0090b

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

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

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

@@ -7,9 +7,10 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1d9df714-a6dc-5dc3-b2ff-c9325f91a443")}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]="e302f519-aa51-503b-bd1a-f3155338f133")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
+import { PM_POSITIONAL_ACTION_CONTRACTS, } from "./grammar-contracts.js";
 function normalizeFlagAliasKey(flag) {
     if (!flag.startsWith("--")) {
         return flag;
@@ -1139,8 +1140,8 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--unset" },
     { flag: "--clear-deps" },
@@ -1187,6 +1188,14 @@ export const ITEM_COMPLETE_FLAG_CONTRACTS = [
     { flag: "--force" },
     { flag: "--author", value_name: "value" },
 ];
+/** Recurrence transition flags shared by CLI, SDK, MCP, help, and completion. */
+export const ITEM_REOPEN_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
+    { flag: "--status", value_name: "open|in_progress" },
+    { flag: "--message", value_name: "value" },
+    { flag: "--force" },
+    { flag: "--author", value_name: "value" },
+];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export const COPY_FLAG_CONTRACTS = [
     { flag: "--id", value_name: "item-id" },
@@ -1240,8 +1249,8 @@ export const UPDATE_FLAG_CONTRACTS = [
     { flag: "--comment" },
     { flag: "--note" },
     { flag: "--learning" },
-    { flag: "--file" },
-    { flag: "--test" },
+    { flag: "--file", aliases: ["--linked-file"] },
+    { flag: "--test", aliases: ["--linked-test"] },
     { flag: "--doc" },
     { flag: "--reminder" },
     { flag: "--event" },
@@ -1636,7 +1645,33 @@ export function toUniqueFlagContracts(contracts) {
     return unique;
 }
 function withSubcommandGlobalFlags(contracts) {
-    return withFlagAliasMetadata(toUniqueFlagContracts([...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]));
+    const byCanonicalFlag = new Map();
+    for (const contract of [...SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, ...contracts]) {
+        const canonicalFlag = normalizeFlagAliasKey(contract.flag);
+        const prior = byCanonicalFlag.get(canonicalFlag);
+        const { aliases: declaredAliases, ...contractWithoutAliases } = contract;
+        const aliases = normalizeUniqueStringList([
+            ...(declaredAliases ?? []),
+            ...(contract.flag === canonicalFlag ? [] : [contract.flag]),
+        ]).filter((alias) => alias !== canonicalFlag);
+        const normalizedContract = {
+            ...contractWithoutAliases,
+            flag: canonicalFlag,
+            ...(aliases.length > 0 ? { aliases } : {}),
+        };
+        const mergedAliases = normalizeUniqueStringList([
+            ...(prior?.aliases ?? []),
+            ...(normalizedContract.aliases ?? []),
+        ]);
+        byCanonicalFlag.set(canonicalFlag, prior === undefined
+            ? normalizedContract
+            : {
+                ...prior,
+                ...normalizedContract,
+                ...(mergedAliases.length > 0 ? { aliases: mergedAliases } : {}),
+            });
+    }
+    return withFlagAliasMetadata([...byCanonicalFlag.values()]);
 }
 const FIXED_STATUS_LIST_COMMAND_ALIASES = [
     "list-draft",
@@ -1648,6 +1683,43 @@ const FIXED_STATUS_LIST_COMMAND_ALIASES = [
 ];
 const FIXED_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status" && contract.flag !== "--all");
 const ALL_STATUS_LIST_FLAG_CONTRACTS = LIST_FILTER_FLAG_CONTRACTS.filter((contract) => contract.flag !== "--status");
+function indexCliFlagContracts(contracts) {
+    const index = new Map();
+    for (const contract of contracts) {
+        for (const spelling of [contract.flag, ...(contract.aliases ?? [])]) {
+            const matches = index.get(spelling) ?? [];
+            matches.push(contract);
+            index.set(spelling, matches);
+        }
+    }
+    return index;
+}
+const PLAN_FLAG_CONTRACT_INDEX = indexCliFlagContracts(PLAN_FLAG_CONTRACTS);
+const ASSURANCE_FLAG_CONTRACT_INDEX = indexCliFlagContracts(ASSURANCE_FLAG_CONTRACTS);
+const POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT = new Map([
+    ["assurance", ASSURANCE_FLAG_CONTRACT_INDEX],
+    ["plan", PLAN_FLAG_CONTRACT_INDEX],
+    ["workspace snapshot", indexCliFlagContracts(WORKSPACE_FLAG_CONTRACTS)],
+]);
+/** Resolve every positional action's accepted flags against one parent contract. */
+export function resolvePmPositionalActionFlagContracts(actions = PM_POSITIONAL_ACTION_CONTRACTS) {
+    return actions.map(({ command, parent, accepted_flags: acceptedFlags }) => {
+        const parentFlagIndex = POSITIONAL_ACTION_FLAG_INDEX_BY_PARENT.get(parent);
+        if (!parentFlagIndex) {
+            throw new Error(`Positional action ${command} has no flag-contract index for ${parent}.`);
+        }
+        const selected = acceptedFlags.map((acceptedFlag) => {
+            const matches = parentFlagIndex.get(acceptedFlag) ?? [];
+            if (matches.length !== 1) {
+                throw new Error(`Positional action ${command} accepted flag ${acceptedFlag} does not resolve to exactly one ${parent} flag contract.`);
+            }
+            return matches[0];
+        });
+        return [command, selected];
+    });
+}
+/** Validated positional action flag entries shared by registration and contracts. */
+export const PM_POSITIONAL_ACTION_FLAG_CONTRACTS = resolvePmPositionalActionFlagContracts();
 // Single-token command (plus the `list`/`cal`/`ctx`/`templates` aliases) → its
 // dedicated flag-contract table. Lookups fall back to the subcommand-global set,
 // so tokens absent here (`reindex`, `help`, or any unknown command) degrade to
@@ -1676,6 +1748,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["create", CREATE_FLAG_CONTRACTS],
     ["item mutate", ITEM_MUTATE_FLAG_CONTRACTS],
     ["item complete", ITEM_COMPLETE_FLAG_CONTRACTS],
+    ["item reopen", ITEM_REOPEN_FLAG_CONTRACTS],
     ["copy", COPY_FLAG_CONTRACTS],
     ["focus", FOCUS_FLAG_CONTRACTS],
     ["aggregate", AGGREGATE_FLAG_CONTRACTS],
@@ -1723,6 +1796,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["telemetry", TELEMETRY_FLAG_CONTRACTS],
     ["health", HEALTH_FLAG_CONTRACTS],
     ["assurance", ASSURANCE_FLAG_CONTRACTS],
+    ...PM_POSITIONAL_ACTION_FLAG_CONTRACTS,
     ["validate", VALIDATE_FLAG_CONTRACTS],
     ["gc", GC_FLAG_CONTRACTS],
     ["stats", STATS_FLAG_CONTRACTS],
@@ -1751,6 +1825,7 @@ const EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND = new Map([
     ["reload", EXTENSION_RELOAD_FLAG_CONTRACTS],
     ["doctor", EXTENSION_DOCTOR_FLAG_CONTRACTS],
     ["catalog", EXTENSION_CATALOG_FLAG_CONTRACTS],
+    ["list", EXTENSION_CATALOG_FLAG_CONTRACTS],
     ["adopt", EXTENSION_ADOPT_FLAG_CONTRACTS],
     ["adopt-all", EXTENSION_ADOPT_ALL_FLAG_CONTRACTS],
     ["activate", EXTENSION_ACTIVATE_FLAG_CONTRACTS],
@@ -1776,11 +1851,12 @@ export function hasSubcommandFlagContractsForCommand(commandName) {
         lifecycleSubcommand !== undefined &&
         extraParts.length === 0 &&
         (lifecycleSubcommand === "init" ||
+            lifecycleSubcommand === "scaffold" ||
             EXTENSION_LIFECYCLE_FLAG_CONTRACTS_BY_SUBCOMMAND.has(lifecycleSubcommand)));
 }
 /** Resolves the flag contracts an `extension`/`package <subcommand>` lifecycle invocation accepts. `init` carries the package-only `--declarative` flag, so `package`/`packages init` resolve to the package init table while `extension init` resolves to the extension init table; every other lifecycle subcommand shares one table, and an unknown subcommand falls back to globals-only. */
 function resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand) {
-    if (lifecycleSubcommand === "init") {
+    if (lifecycleSubcommand === "init" || lifecycleSubcommand === "scaffold") {
         // `--declarative` is package-only, so `package init` / `packages init` carry it.
         return rootCommand === "extension"
             ? EXTENSION_INIT_FLAG_CONTRACTS
@@ -1825,4 +1901,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=1d9df714-a6dc-5dc3-b2ff-c9325f91a443
+//# debugId=e302f519-aa51-503b-bd1a-f3155338f133

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

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

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

@@ -0,0 +1,340 @@
+/**
+ * @module sdk/flag-lexicon-contracts
+ *
+ * Compiles command flags into a canonical concept lexicon with enforceable
+ * per-command growth budgets.
+ */
+
+!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]="6ba3d756-dcd6-59b7-92fe-ec33d294d72b")}catch(e){}}();
+import { hasSubcommandFlagContractsForCommand, resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
+import { PM_COMMAND_CAPABILITY_CONTRACTS, } from "../agent-capability-contracts.js";
+import { enrichCliFlagInvocationContracts } from "../flag-invocation-contracts.js";
+/** Memoized immutable canonical lexicon for this module instance. */
+let cachedPmFlagLexicon;
+const FULL_PROJECTION_CONCEPT_BY_COMMAND = Object.freeze({
+    list: "list-item-projection",
+    "list-all": "list-item-projection",
+    "list-draft": "list-item-projection",
+    "list-open": "list-item-projection",
+    "list-in-progress": "list-item-projection",
+    "list-blocked": "list-item-projection",
+    "list-closed": "list-item-projection",
+    "list-canceled": "list-item-projection",
+    get: "get-item-projection",
+    graph: "graph-detail-projection",
+    search: "search-result-projection",
+    history: "history-entry-projection",
+    events: "mutation-event-projection",
+    activity: "activity-entry-projection",
+    deps: "dependency-graph-projection",
+    health: "health-diagnostic-projection",
+    validate: "validation-diagnostic-projection",
+    contracts: "contract-catalog-projection",
+});
+/** Resolve one executable command flag to its stable cross-command semantic concept. */
+export function resolvePmFlagSemanticConcept(command, flag) {
+    if (flag === "--limit")
+        return "result-row-limit";
+    if (flag === "--node-limit")
+        return "graph-node-limit";
+    if (flag === "--edge-limit")
+        return "graph-edge-limit";
+    if (flag === "--output-limit")
+        return "rendered-output-row-limit";
+    if (flag === "--output-budget")
+        return "rendered-output-byte-budget";
+    if (flag === "--token-budget")
+        return "context-intent-token-budget";
+    if (flag === "--full") {
+        const concept = FULL_PROJECTION_CONCEPT_BY_COMMAND[command];
+        if (concept === undefined) {
+            throw new Error(`Command ${command} exposes --full without a registered projection concept.`);
+        }
+        return concept;
+    }
+    if (flag !== "--file")
+        return flag.slice(2);
+    if (["create", "update", "update-many"].includes(command))
+        return "linked-file-path";
+    if (["comments", "notes", "learnings"].includes(command))
+        return "entry-file-input";
+    return "plan-definition-file";
+}
+/** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
+export function listPmFlagLexicon() {
+    if (cachedPmFlagLexicon !== undefined)
+        return cachedPmFlagLexicon;
+    const commandContracts = PM_COMMAND_CAPABILITY_CONTRACTS.filter(({ command }) => hasSubcommandFlagContractsForCommand(command));
+    const provisionalEntries = commandContracts.flatMap(({ command, family }) => enrichCliFlagInvocationContracts(command, resolveSubcommandFlagContractsForCommand(command)).map((contract) => ({
+        command,
+        family,
+        concept: resolvePmFlagSemanticConcept(command, contract.flag),
+        flag: contract.flag,
+        aliases: Object.freeze([...(contract.aliases ?? [])]),
+        value_kind: (contract.repeatable
+            ? "list"
+            : contract.flag === "--limit"
+                ? "number"
+                : contract.value_type),
+    })));
+    const compatibilityAliasFlags = new Set(provisionalEntries.flatMap((entry) => entry.aliases.map((alias) => `${entry.command}:${alias}`)));
+    const canonicalEntries = provisionalEntries.filter((entry) => !compatibilityAliasFlags.has(`${entry.command}:${entry.flag}`));
+    const kindsByConcept = new Map();
+    for (const entry of canonicalEntries) {
+        const kinds = kindsByConcept.get(entry.concept) ?? new Set();
+        kinds.add(entry.value_kind);
+        kindsByConcept.set(entry.concept, kinds);
+    }
+    cachedPmFlagLexicon = Object.freeze(canonicalEntries.map((entry) => Object.freeze({
+        ...entry,
+        concept: kindsByConcept.get(entry.concept)?.size === 1
+            ? entry.concept
+            : `${entry.concept}@${entry.command}`,
+    })));
+    return cachedPmFlagLexicon;
+}
+/** Return the complete canonical and compatibility spelling inventory. */
+export function listPmFlagSpellingInventory() {
+    return Object.freeze(listPmFlagLexicon().map((entry) => Object.freeze({
+        command: entry.command,
+        canonical_flag: entry.flag,
+        accepted_spellings: Object.freeze([...new Set([entry.flag, ...entry.aliases])].sort()),
+    })));
+}
+const PM_COMMAND_FLAG_BUDGET_MAXIMUMS = Object.freeze({
+    init: 30,
+    config: 35,
+    extension: 53,
+    package: 54,
+    packages: 54,
+    install: 26,
+    upgrade: 29,
+    create: 100,
+    copy: 24,
+    focus: 22,
+    list: 86,
+    "list-all": 85,
+    "list-draft": 84,
+    "list-open": 84,
+    "list-in-progress": 84,
+    "list-blocked": 84,
+    "list-closed": 84,
+    "list-canceled": 84,
+    aggregate: 37,
+    context: 45,
+    ctx: 45,
+    get: 30,
+    graph: 34,
+    search: 78,
+    duplicates: 24,
+    eval: 25,
+    next: 35,
+    history: 35,
+    events: 33,
+    "history-redact": 27,
+    "history-repair": 26,
+    "history-compact": 30,
+    "history-author-acknowledge": 28,
+    merge: 24,
+    schema: 40,
+    profile: 22,
+    activity: 35,
+    restore: 23,
+    update: 105,
+    "update-many": 140,
+    close: 31,
+    "close-many": 72,
+    delete: 24,
+    append: 24,
+    comments: 30,
+    notes: 34,
+    learnings: 26,
+    files: 39,
+    docs: 30,
+    deps: 32,
+    plan: 109,
+    test: 48,
+    "test-all": 37,
+    telemetry: 21,
+    stats: 29,
+    health: 36,
+    validate: 45,
+    assurance: 30,
+    gc: 22,
+    workspace: 23,
+    contracts: 29,
+    claim: 36,
+    release: 23,
+    "start-task": 23,
+    "pause-task": 23,
+    "close-task": 24,
+    meet: 33,
+    event: 33,
+    remind: 29,
+    "test-runs-worker": 25,
+});
+/** Return persisted no-growth ratchets with current counts derived from the canonical vocabulary. */
+export function listPmCommandFlagBudgets() {
+    const currentByCommand = new Map(Object.keys(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map((command) => [command, 0]));
+    for (const { command } of listPmFlagLexicon()) {
+        currentByCommand.set(command, Number(currentByCommand.get(command)) + 1);
+    }
+    return Object.freeze(Object.entries(PM_COMMAND_FLAG_BUDGET_MAXIMUMS).map(([command, maximum]) => Object.freeze({
+        command,
+        current: Number(currentByCommand.get(command)),
+        maximum,
+    })));
+}
+/** Append collisions between compatibility aliases and canonical spellings. */
+function appendAliasCollisionFindings(entries, canonicalOwners, findings) {
+    for (const entry of entries) {
+        for (const alias of entry.aliases) {
+            const owner = canonicalOwners.get(`${entry.command}:${alias}`);
+            if (owner === undefined || owner.flag === entry.flag)
+                continue;
+            findings.push({
+                code: "alias_collision",
+                command: entry.command,
+                detail: `${alias} aliases ${entry.flag} but is canonical for ${owner.flag}.`,
+            });
+        }
+    }
+}
+/** Append missing, stale, and exceeded command-budget findings. */
+function appendBudgetFindings(counts, budgets, findings) {
+    const budgetedCommands = new Set(budgets.map(({ command }) => command));
+    for (const command of counts.keys()) {
+        if (budgetedCommands.has(command))
+            continue;
+        findings.push({
+            code: "missing_budget",
+            command,
+            detail: `${command} has canonical flags but no persisted budget.`,
+        });
+    }
+    for (const budget of budgets) {
+        const actual = counts.get(budget.command) ?? 0;
+        if (actual === 0) {
+            findings.push({
+                code: "stale_budget",
+                command: budget.command,
+                detail: `${budget.command} has a persisted budget but no canonical flags.`,
+            });
+        }
+        if (actual <= budget.maximum)
+            continue;
+        findings.push({
+            code: "budget_exceeded",
+            command: budget.command,
+            detail: `${actual} canonical flags exceed the ratcheted maximum ${budget.maximum}.`,
+        });
+    }
+}
+/** Append regressions against the persisted pre-change spelling inventory. */
+function appendSpellingCompatibilityFindings(entries, baseline, findings) {
+    const current = new Map(entries.map((entry) => [`${entry.command}:${entry.flag}`, entry]));
+    for (const historical of baseline) {
+        const key = `${historical.command}:${historical.canonical_flag}`;
+        const entry = current.get(key);
+        if (!entry) {
+            findings.push({
+                code: "removed_canonical_spelling",
+                command: historical.command,
+                detail: `${historical.canonical_flag} disappeared from the executable spelling inventory.`,
+            });
+            continue;
+        }
+        const accepted = new Set([entry.flag, ...entry.aliases]);
+        for (const spelling of historical.accepted_spellings) {
+            if (accepted.has(spelling))
+                continue;
+            findings.push({
+                code: "removed_compatibility_spelling",
+                command: historical.command,
+                detail: `${spelling} no longer resolves to ${historical.canonical_flag}.`,
+            });
+        }
+    }
+}
+/** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
+export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets(), baseline = []) {
+    const findings = [];
+    const canonicalOwners = new Map();
+    const conceptKinds = new Map();
+    const conceptSpellings = new Map();
+    const counts = new Map();
+    for (const entry of entries) {
+        const commandFlag = `${entry.command}:${entry.flag}`;
+        if (canonicalOwners.has(commandFlag)) {
+            findings.push({
+                code: "duplicate_canonical_flag",
+                command: entry.command,
+                detail: `${entry.flag} has more than one canonical row.`,
+            });
+        }
+        else {
+            canonicalOwners.set(commandFlag, entry);
+        }
+        counts.set(entry.command, (counts.get(entry.command) ?? 0) + 1);
+        const priorKind = conceptKinds.get(entry.concept);
+        if (priorKind !== undefined && priorKind !== entry.value_kind) {
+            findings.push({
+                code: "inconsistent_concept_kind",
+                command: entry.command,
+                detail: `${entry.concept} uses both ${priorKind} and ${entry.value_kind}.`,
+            });
+        }
+        else {
+            conceptKinds.set(entry.concept, entry.value_kind);
+        }
+        const priorSpelling = conceptSpellings.get(entry.concept);
+        if (priorSpelling !== undefined && priorSpelling !== entry.flag) {
+            findings.push({
+                code: "semantic_spelling_collision",
+                command: entry.command,
+                detail: `${entry.concept} is canonicalized by both ${priorSpelling} and ${entry.flag}.`,
+            });
+        }
+        else {
+            conceptSpellings.set(entry.concept, entry.flag);
+        }
+    }
+    appendAliasCollisionFindings(entries, canonicalOwners, findings);
+    appendBudgetFindings(counts, budgets, findings);
+    appendSpellingCompatibilityFindings(entries, baseline, findings);
+    findings.sort((left, right) => left.command.localeCompare(right.command) ||
+        left.code.localeCompare(right.code) ||
+        left.detail.localeCompare(right.detail));
+    return {
+        ok: findings.length === 0,
+        entry_count: entries.length,
+        budget_count: budgets.length,
+        concept_count: new Set(entries.map(({ concept }) => concept)).size,
+        baseline_entry_count: baseline.length,
+        findings,
+    };
+}
+/** Render a compact, generated family and command budget reference. Persisted budget rows are initialized to an explicit fallback so stale rows remain renderable. */
+export function renderPmFlagLexiconMarkdown() {
+    const lexicon = listPmFlagLexicon();
+    const budgets = listPmCommandFlagBudgets();
+    const familyByCommand = new Map(budgets.map(({ command }) => [command, "unknown"]));
+    for (const { command, family } of lexicon)
+        familyByCommand.set(command, family);
+    const rows = budgets.map(({ command, current, maximum }) => {
+        const family = familyByCommand.get(command);
+        return `| \`${command}\` | ${family} | ${current} | ${maximum} |`;
+    });
+    return [
+        "# Generated flag lexicon budgets",
+        "",
+        "This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not consume canonical budget.",
+        "",
+        "| Command | Capability family | Canonical flags | Maximum |",
+        "| --- | --- | ---: | ---: |",
+        ...rows,
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=flag-lexicon-contracts.js.map
+//# debugId=6ba3d756-dcd6-59b7-92fe-ec33d294d72b