@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -10,7 +10,7 @@ import type { PmCommandAliasContract } from "./command-aliases.js";
 /** Canonical top-level domains an agent must retain to route pm operations. */
 export declare const PM_CLI_GRAMMAR_NOUNS: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
 /** Shared verbs whose meaning transfers across domain nouns. */
-export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+export declare const PM_CLI_SHARED_VERBS: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
 /** Why a current command is permitted while the grammar migration proceeds. */
 export type PmCommandDestinationDisposition = "target_noun" | "consolidation" | "package_owned" | "keep_as_is";
 /** Exact destination decision for one command emitted by runtime contracts. */
@@ -28,16 +28,97 @@ export interface PmCommandDestinationContract {
     /** Reason required only for a deliberate keep-as-is exception. */
     reason?: string;
 }
+/** Semantic value class for one positional slot, independent of its display label. */
+export type PmCommandPositionalValueKind = "action" | "integer" | "item_id" | "string";
+/** One ordered positional slot accepted by a command path. */
+export interface PmCommandPositionalSlotContract {
+    /** Stable agent-facing slot name. */
+    name: string;
+    /** Whether Commander and the SDK action both require the slot. */
+    required: boolean;
+    /** Whether the final slot consumes every remaining positional token. */
+    variadic: boolean;
+    /** Semantic value class used to compare shapes across commands. */
+    value_kind: PmCommandPositionalValueKind;
+    /** Whether the slot accepts more than one concept for compatibility. */
+    polymorphic: boolean;
+}
+/** Complete positional signature for one executable or virtual action path. */
+export interface PmCommandPositionalContract {
+    /** Normalized command path. */
+    command: string;
+    /** Ordered positional slots after the command path. */
+    slots: readonly PmCommandPositionalSlotContract[];
+}
+/** Discoverable positional action projected through help, contracts, and completion. */
+export interface PmPositionalActionContract extends PmCommandPositionalContract {
+    /** Commander command that dispatches the action positionally. */
+    parent: "assurance" | "plan" | "workspace snapshot";
+    /** Literal action token accepted in the parent's first positional slot. */
+    action: string;
+    /** Canonical flags applicable to this action-specific view. */
+    accepted_flags: readonly string[];
+    /** Concise action-specific intent. */
+    description: string;
+    /** Executable example suitable for recovery and help output. */
+    example: string;
+}
+/** Virtual action paths dispatched by positional parent commands. */
+export declare const PM_POSITIONAL_ACTION_CONTRACTS: readonly PmPositionalActionContract[];
+/** Resolve one declared signature without treating arbitrary object keys as commands. */
+export declare function resolvePmCommandPositionalContract(command: string): PmCommandPositionalContract | undefined;
+/** Resolve one action-specific help/contract view. */
+export declare function resolvePmPositionalActionContract(command: string): PmPositionalActionContract | undefined;
+/** Format the shared action-flag tip rendered by text and structured help. */
+export declare function formatPmPositionalActionFlagTip(acceptedFlags: readonly string[]): string;
 /** Checked-in exhaustive destination census for core and known package commands. */
 export declare const PM_COMMAND_DESTINATION_CONTRACTS: readonly PmCommandDestinationContract[];
+/** Exhaustive current command and positional-action signature table. */
+export declare const PM_COMMAND_POSITIONAL_CONTRACTS: readonly PmCommandPositionalContract[];
 /** Immutable grammar policy used by contracts and the CI gate. */
 export declare const PM_CLI_GRAMMAR_CONTRACT: {
     readonly nouns: readonly ["item", "list", "context", "search", "graph", "history", "workspace", "package", "ops", "plan", "contracts", "help"];
-    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "repair", "restore", "run", "show", "uninstall", "verify"];
+    readonly shared_verbs: readonly ["activate", "add", "adopt", "adopt-all", "catalog", "compact", "complete", "create", "deactivate", "delete", "describe", "doctor", "edit", "explore", "import", "init", "inspect", "install", "list", "manage", "migrate", "mutate", "read", "redact", "reload", "remove", "reopen", "repair", "restore", "run", "show", "uninstall", "verify"];
     readonly scope_before_verb: true;
     readonly visible_top_level_ceiling: 69;
     readonly ceiling_raise_requires_pm_item: true;
+    readonly positional_shape_budget: 21;
 };
+/** One positional-signature drift finding. */
+export interface PmCommandPositionalFinding {
+    /** Stable remediation category. */
+    code: "missing_observed_signature" | "positional_shape_budget_exceeded" | "positional_signature_mismatch" | "stale_observed_signature";
+    /** Command path whose positional contract drifted. */
+    command: string;
+    /** Actionable mismatch detail. */
+    detail: string;
+}
+/** Complete positional grammar conformance receipt. */
+export interface PmCommandPositionalReport {
+    /** Whether the observed signatures exactly match the declaration. */
+    ok: boolean;
+    /** Declared command/action paths. */
+    declared_command_count: number;
+    /** Independently observed command/action paths. */
+    observed_command_count: number;
+    /** Number of distinct semantic positional shapes. */
+    positional_shape_count: number;
+    /** Maximum distinct shapes allowed without a tracked grammar decision. */
+    positional_shape_budget: number;
+    /** Stable positional conformance failures. */
+    findings: PmCommandPositionalFinding[];
+}
+/** Report explicit positional entries that no destination command declares. */
+export declare function verifyExplicitPositionalSlotCensus(explicitCommands: Iterable<string>, destinationCommands: Iterable<string>): PmCommandPositionalFinding[];
+/** Return the semantic shape identity used by the positional-shape budget. */
+export declare function positionalShapeKey(slots: readonly PmCommandPositionalSlotContract[]): string;
+/** Return the exact canonical identity of an ordered positional signature. */
+export declare function positionalSignatureKey(slots: readonly PmCommandPositionalSlotContract[]): string;
+/** Compare independently observed Commander signatures with the SDK declaration. */
+export declare function verifyPmCommandPositionalContracts(observed: readonly PmCommandPositionalContract[], options?: {
+    declared?: readonly PmCommandPositionalContract[];
+    positionalShapeBudget?: number;
+}): PmCommandPositionalReport;
 /** One self-correcting grammar-gate finding. */
 export interface PmCliGrammarFinding {
     /** Stable diagnostic category suitable for automated remediation. */