@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -1,6 +1,6 @@
 /** Canonical top-level domains an agent must retain to route pm operations. */
 
-!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]="b959d41a-c0b6-55fe-a426-0be073f0511c")}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]="21495fd2-6abb-5a4f-965c-e7b9c8f87dff")}catch(e){}}();
 export const PM_CLI_GRAMMAR_NOUNS = [
     "item",
     "list",
@@ -43,6 +43,7 @@ export const PM_CLI_SHARED_VERBS = [
     "redact",
     "reload",
     "remove",
+    "reopen",
     "repair",
     "restore",
     "run",
@@ -50,6 +51,495 @@ export const PM_CLI_SHARED_VERBS = [
     "uninstall",
     "verify",
 ];
+function positionalSlot(name, valueKind, required, options = {}) {
+    return {
+        name,
+        required,
+        variadic: options.variadic === true,
+        value_kind: valueKind,
+        polymorphic: options.polymorphic === true,
+    };
+}
+/** Convert a kebab-case positional action into a sentence-leading verb phrase. */
+function positionalActionVerb(action) {
+    const phrase = action.replaceAll("-", " ");
+    return `${phrase.charAt(0).toUpperCase()}${phrase.slice(1)}`;
+}
+const ITEM_ID = positionalSlot("id", "item_id", true);
+const OPTIONAL_ITEM_ID = positionalSlot("id", "item_id", false);
+const OPTIONAL_TEXT = positionalSlot("text", "string", false);
+const PLAN_ITEM_ID = positionalSlot("plan-id", "item_id", true);
+const PLAN_STEP = positionalSlot("step", "string", true);
+const PLAN_CREATE_FLAGS = [
+    "--acceptance-criteria",
+    "--actual-result",
+    "--affected-version",
+    "--assignee",
+    "--blocked-by",
+    "--blocked-reason",
+    "--blocks",
+    "--body",
+    "--claim",
+    "--comment",
+    "--component",
+    "--confidence",
+    "--create-mode",
+    "--customer-impact",
+    "--deadline",
+    "--definition-of-ready",
+    "--description",
+    "--doc",
+    "--environment",
+    "--estimate",
+    "--event",
+    "--expected-result",
+    "--fixed-version",
+    "--file",
+    "--from-search",
+    "--goal",
+    "--harness",
+    "--impact",
+    "--learning",
+    "--message",
+    "--mode",
+    "--note",
+    "--objective",
+    "--order",
+    "--outcome",
+    "--parent",
+    "--priority",
+    "--rank",
+    "--related",
+    "--release",
+    "--reminder",
+    "--reporter",
+    "--repro-steps",
+    "--resolution",
+    "--resume-context",
+    "--reviewer",
+    "--risk",
+    "--scope",
+    "--severity",
+    "--sprint",
+    "--status",
+    "--step",
+    "--step-blocked-reason",
+    "--step-body",
+    "--step-evidence",
+    "--step-owner",
+    "--step-replacement",
+    "--step-status",
+    "--step-title",
+    "--tags",
+    "--template",
+    "--test",
+    "--title",
+    "--type-option",
+    "--unblock-note",
+    "--value",
+    "--why-now",
+];
+const PLAN_STEP_FLAGS = [
+    "--allow-multiple-active",
+    "--depends-on",
+    "--file",
+    "--force",
+    "--message",
+    "--step-blocked-reason",
+    "--step-body",
+    "--step-evidence",
+    "--step-owner",
+    "--step-status",
+    "--step-title",
+    "--test",
+];
+const PLAN_STEP_ACTION_DESCRIPTIONS = {
+    "update-step": "Update one declared Plan step.",
+    "complete-step": "Complete one declared Plan step.",
+    "block-step": "Block one declared Plan step.",
+    "remove-step": "Remove one declared Plan step.",
+    link: "Link one dependency to a declared Plan step.",
+    unlink: "Unlink one dependency from a declared Plan step.",
+};
+/** Virtual action paths dispatched by positional parent commands. */
+export const PM_POSITIONAL_ACTION_CONTRACTS = [
+    {
+        command: "plan create",
+        parent: "plan",
+        action: "create",
+        slots: [positionalSlot("title", "string", false, { polymorphic: true })],
+        accepted_flags: PLAN_CREATE_FLAGS,
+        description: "Create a Plan item and optionally seed its ordered steps.",
+        example: 'pm plan create --title "Refactor lock retry"',
+    },
+    {
+        command: "plan show",
+        parent: "plan",
+        action: "show",
+        slots: [PLAN_ITEM_ID],
+        accepted_flags: ["--depth", "--fields"],
+        description: "Read one Plan item with a bounded plan projection.",
+        example: "pm plan show pm-a1b2 --depth standard",
+    },
+    {
+        command: "plan add-step",
+        parent: "plan",
+        action: "add-step",
+        slots: [PLAN_ITEM_ID],
+        accepted_flags: PLAN_STEP_FLAGS,
+        description: "Append one ordered step to a Plan item.",
+        example: 'pm plan add-step pm-a1b2 --step-title "Run tests"',
+    },
+    ...Object.entries(PLAN_STEP_ACTION_DESCRIPTIONS).map(([action, description]) => ({
+        command: `plan ${action}`,
+        parent: "plan",
+        action,
+        slots: [PLAN_ITEM_ID, PLAN_STEP],
+        accepted_flags: PLAN_STEP_FLAGS,
+        description,
+        example: `pm plan ${action} pm-a1b2 plan-step-001`,
+    })),
+    {
+        command: "plan reorder-step",
+        parent: "plan",
+        action: "reorder-step",
+        slots: [
+            PLAN_ITEM_ID,
+            PLAN_STEP,
+            positionalSlot("new-order", "integer", true),
+        ],
+        accepted_flags: ["--force", "--message"],
+        description: "Move one Plan step to a declared integer order.",
+        example: "pm plan reorder-step pm-a1b2 plan-step-001 2",
+    },
+    ...[
+        "decision",
+        "discovery",
+        "validation",
+        "resume",
+        "approve",
+        "materialize",
+    ].map((action) => ({
+        command: `plan ${action}`,
+        parent: "plan",
+        action,
+        slots: [PLAN_ITEM_ID],
+        accepted_flags: PLAN_STEP_FLAGS,
+        description: `${positionalActionVerb(action)} for one Plan item.`,
+        example: `pm plan ${action} pm-a1b2`,
+    })),
+    ...["list", "show", "put", "remove"].map((action) => ({
+        command: `assurance ${action}`,
+        parent: "assurance",
+        action,
+        slots: [
+            positionalSlot("kind", "string", true),
+            ...(action === "list" ? [] : [positionalSlot("id", "string", true)]),
+        ],
+        accepted_flags: action === "put"
+            ? ["--author", "--definition", "--message"]
+            : action === "remove"
+                ? ["--author", "--message"]
+                : [],
+        description: `${positionalActionVerb(action)} assurance declarations by kind.`,
+        example: action === "list"
+            ? "pm assurance list measurement"
+            : `pm assurance ${action} measurement example-id`,
+    })),
+    {
+        command: "assurance run",
+        parent: "assurance",
+        action: "run",
+        slots: [positionalSlot("gate-id", "string", true)],
+        accepted_flags: ["--dry-run", "--trigger", "--tree"],
+        description: "Evaluate one assurance gate for a lifecycle trigger.",
+        example: "pm assurance run tracker-context-quality --trigger ci --dry-run",
+    },
+    {
+        command: "assurance verdicts",
+        parent: "assurance",
+        action: "verdicts",
+        slots: [positionalSlot("gate-id", "string", false)],
+        accepted_flags: ["--gate", "--limit"],
+        description: "List bounded assurance verdict history.",
+        example: "pm assurance verdicts --limit 20",
+    },
+    ...["presets", "apply"].map((action) => ({
+        command: `assurance ${action}`,
+        parent: "assurance",
+        action,
+        slots: [positionalSlot("preset", "string", action === "apply")],
+        accepted_flags: ["--author", "--message", "--owner"],
+        description: action === "apply"
+            ? "Apply one assurance adoption preset."
+            : "List available assurance adoption presets.",
+        example: action === "apply"
+            ? "pm assurance apply software-delivery --owner <pm-item-id>"
+            : "pm assurance presets",
+    })),
+    {
+        command: "assurance derive",
+        parent: "assurance",
+        action: "derive",
+        slots: [],
+        accepted_flags: ["--apply", "--author", "--message", "--owner"],
+        description: "Derive assurance proposals from current project context.",
+        example: "pm assurance derive --owner pm-a1b2",
+    },
+    {
+        command: "assurance promote",
+        parent: "assurance",
+        action: "promote",
+        slots: [positionalSlot("assertion-id", "string", true)],
+        accepted_flags: ["--author", "--enforcement", "--message"],
+        description: "Promote one assertion into a warning or blocking gate.",
+        example: "pm assurance promote assertion-id --enforcement warn",
+    },
+    {
+        command: "assurance risk",
+        parent: "assurance",
+        action: "risk",
+        slots: [],
+        accepted_flags: ["--definition"],
+        description: "Analyze bounded defect-recurrence risk for a proposed change.",
+        example: 'pm assurance risk --definition \'{"change":{"files":[]}}\'',
+    },
+    {
+        command: "workspace snapshot create",
+        parent: "workspace snapshot",
+        action: "create",
+        slots: [positionalSlot("name", "string", false)],
+        accepted_flags: [],
+        description: "Capture authoritative tracker state as an immutable snapshot.",
+        example: "pm workspace snapshot create before-migration",
+    },
+    {
+        command: "workspace snapshot list",
+        parent: "workspace snapshot",
+        action: "list",
+        slots: [],
+        accepted_flags: [],
+        description: "List immutable workspace snapshots and named references.",
+        example: "pm workspace snapshot list",
+    },
+    {
+        command: "workspace snapshot inspect",
+        parent: "workspace snapshot",
+        action: "inspect",
+        slots: [positionalSlot("target", "string", true)],
+        accepted_flags: [],
+        description: "Inspect one workspace snapshot target.",
+        example: "pm workspace snapshot inspect before-migration",
+    },
+    {
+        command: "workspace snapshot restore",
+        parent: "workspace snapshot",
+        action: "restore",
+        slots: [positionalSlot("target", "string", true)],
+        accepted_flags: ["--author", "--dry-run", "--force", "--message"],
+        description: "Restore an immutable workspace snapshot with explicit recovery controls.",
+        example: "pm workspace snapshot restore before-migration --dry-run",
+    },
+    {
+        command: "workspace snapshot delete",
+        parent: "workspace snapshot",
+        action: "delete",
+        slots: [positionalSlot("target", "string", true)],
+        accepted_flags: [],
+        description: "Delete one workspace snapshot target.",
+        example: "pm workspace snapshot delete before-migration",
+    },
+];
+const POSITIONAL_ACTION_CONTRACTS_BY_SPECIFICITY = [
+    ...PM_POSITIONAL_ACTION_CONTRACTS,
+].sort((left, right) => right.command.length - left.command.length);
+const EXPLICIT_POSITIONAL_SLOTS = new Map([
+    ["append", [ITEM_ID, OPTIONAL_TEXT]],
+    [
+        "assurance",
+        [
+            positionalSlot("action", "action", true),
+            positionalSlot("kind", "string", false),
+            positionalSlot("id", "string", false),
+        ],
+    ],
+    ["beads import", [positionalSlot("file", "string", false)]],
+    ["changelog export", [positionalSlot("file", "string", false)]],
+    ["claim", [OPTIONAL_ITEM_ID]],
+    ["close", [ITEM_ID, OPTIONAL_TEXT]],
+    ["close-task", [ITEM_ID, positionalSlot("reason", "string", false)]],
+    ["comments", [ITEM_ID, OPTIONAL_TEXT]],
+    ["completion", [positionalSlot("shell", "string", false)]],
+    [
+        "config",
+        [
+            positionalSlot("scope", "string", false, { polymorphic: true }),
+            positionalSlot("action", "action", false),
+            positionalSlot("key", "string", false),
+            positionalSlot("value", "string", false, { polymorphic: true }),
+        ],
+    ],
+    ["copy", [ITEM_ID]],
+    [
+        "create",
+        [
+            positionalSlot("type-or-title", "string", false, { polymorphic: true }),
+            positionalSlot("title", "string", false),
+        ],
+    ],
+    ["delete", [ITEM_ID]],
+    ["deps", [ITEM_ID]],
+    ["docs", [ITEM_ID]],
+    ["event", [positionalSlot("title", "string", true)]],
+    [
+        "extension",
+        [positionalSlot("target", "string", false, { polymorphic: true })],
+    ],
+    ["extension list", []],
+    ["extension scaffold", [positionalSlot("target", "string", true)]],
+    ["files", [ITEM_ID]],
+    ["files discover", [ITEM_ID]],
+    [
+        "files lookup",
+        [positionalSlot("paths", "string", true, { variadic: true })],
+    ],
+    ["focus", [OPTIONAL_ITEM_ID]],
+    ["get", [ITEM_ID]],
+    [
+        "graph",
+        [
+            positionalSlot("subcommand", "action", true),
+            OPTIONAL_ITEM_ID,
+            positionalSlot("target", "item_id", false),
+        ],
+    ],
+    ["guide", [positionalSlot("topic", "string", false)]],
+    ["history", [ITEM_ID]],
+    ["history-compact", [OPTIONAL_ITEM_ID]],
+    ["history-redact", [ITEM_ID]],
+    ["history-repair", [OPTIONAL_ITEM_ID]],
+    [
+        "init",
+        [positionalSlot("prefix-or-path", "string", false, { polymorphic: true })],
+    ],
+    ["install", [positionalSlot("targets", "string", false, { variadic: true })]],
+    ["item complete", [ITEM_ID, positionalSlot("reason", "string", false)]],
+    ["item reopen", [ITEM_ID, positionalSlot("reason", "string", true)]],
+    ["learnings", [ITEM_ID, OPTIONAL_TEXT]],
+    ["meet", [positionalSlot("title", "string", true)]],
+    [
+        "merge",
+        [
+            positionalSlot("subcommand", "action", true),
+            positionalSlot("artifact", "string", false),
+            positionalSlot("base", "string", false),
+            positionalSlot("ours", "string", false),
+            positionalSlot("theirs", "string", false),
+        ],
+    ],
+    ["notes", [ITEM_ID, OPTIONAL_TEXT]],
+    [
+        "package",
+        [positionalSlot("target", "string", false, { polymorphic: true })],
+    ],
+    ["package list", []],
+    ["package scaffold", [positionalSlot("target", "string", true)]],
+    [
+        "packages",
+        [positionalSlot("target", "string", false, { polymorphic: true })],
+    ],
+    ["packages list", []],
+    ["packages scaffold", [positionalSlot("target", "string", true)]],
+    ["pause-task", [ITEM_ID]],
+    [
+        "plan",
+        [
+            positionalSlot("subcommand", "action", true),
+            positionalSlot("id", "item_id", false, { polymorphic: true }),
+            positionalSlot("step", "string", false),
+            positionalSlot("new-order", "integer", false),
+        ],
+    ],
+    [
+        "profile",
+        [
+            positionalSlot("subcommand", "action", true),
+            positionalSlot("name", "string", false),
+        ],
+    ],
+    ["release", [ITEM_ID]],
+    ["remind", [positionalSlot("title", "string", true)]],
+    ["restore", [ITEM_ID, positionalSlot("target", "string", true)]],
+    [
+        "schema",
+        [
+            positionalSlot("subcommand", "action", true),
+            positionalSlot("name", "string", false),
+        ],
+    ],
+    [
+        "search-advanced",
+        [positionalSlot("keywords", "string", true, { variadic: true })],
+    ],
+    ["search", [positionalSlot("keywords", "string", true, { variadic: true })]],
+    ["start-task", [ITEM_ID]],
+    [
+        "telemetry",
+        [
+            positionalSlot("namespace-or-subcommand", "action", false, {
+                polymorphic: true,
+            }),
+            positionalSlot("subcommand", "action", false),
+        ],
+    ],
+    ["test", [ITEM_ID]],
+    ["update", [ITEM_ID]],
+    ["upgrade", [positionalSlot("target", "string", false)]],
+    [
+        "workspace snapshot",
+        [
+            positionalSlot("action", "action", true),
+            positionalSlot("target", "string", false),
+        ],
+    ],
+    ...["activate", "adopt", "deactivate", "init", "uninstall"].flatMap((action) => ["extension", "package", "packages"].map((root) => [
+        `${root} ${action}`,
+        [positionalSlot("target", "string", true)],
+    ])),
+    ...["describe"].flatMap((action) => ["extension", "package", "packages"].map((root) => [
+        `${root} ${action}`,
+        [positionalSlot("target", "string", false)],
+    ])),
+    ...["install"].flatMap((action) => ["extension", "package", "packages"].map((root) => [
+        `${root} ${action}`,
+        [positionalSlot("targets", "string", false, { variadic: true })],
+    ])),
+    ["vcs abandon", [ITEM_ID]],
+    ["vcs create", [positionalSlot("title", "string", true)]],
+    ["vcs merge", [ITEM_ID]],
+    ["vcs propose", [ITEM_ID]],
+    ["vcs ref-create", [positionalSlot("name", "string", true)]],
+    ["vcs show", [ITEM_ID]],
+]);
+/** Normalize a command path for every positional-contract lookup and identity check. */
+function normalizePositionalCommandPath(command) {
+    return command.trim().toLowerCase().replace(/\s+/gu, " ");
+}
+/** Resolve one declared signature without treating arbitrary object keys as commands. */
+export function resolvePmCommandPositionalContract(command) {
+    const normalized = normalizePositionalCommandPath(command);
+    return PM_COMMAND_POSITIONAL_CONTRACTS.find((contract) => contract.command === normalized);
+}
+/** Resolve one action-specific help/contract view. */
+export function resolvePmPositionalActionContract(command) {
+    const normalized = normalizePositionalCommandPath(command);
+    return POSITIONAL_ACTION_CONTRACTS_BY_SPECIFICITY.find((contract) => contract.command === normalized ||
+        normalized.startsWith(`${contract.command} `));
+}
+/** Format the shared action-flag tip rendered by text and structured help. */
+export function formatPmPositionalActionFlagTip(acceptedFlags) {
+    return `Applicable flags: ${acceptedFlags.length > 0 ? acceptedFlags.join(", ") : "none"}.`;
+}
 function destinationRows(noun, target, disposition, owner, commands) {
     return commands.map((command) => ({
         command,
@@ -65,6 +555,7 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "item",
         "item complete",
         "item mutate",
+        "item reopen",
     ]),
     ...destinationRows("item", "item", "consolidation", "pm-yql1", [
         "append",
@@ -88,6 +579,10 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "update",
         "update-many",
     ]),
+    ...destinationRows("item", "item files", "consolidation", "pm-ya7x55", [
+        "files discover",
+        "files lookup",
+    ]),
     ...destinationRows("list", "list", "target_noun", "pm-pfqi", ["list"]),
     ...destinationRows("list", "list --group-by", "consolidation", "pm-xkgq", [
         "aggregate",
@@ -153,9 +648,11 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "package explore",
         "package init",
         "package install",
+        "package list",
         "package manage",
         "package migrate",
         "package reload",
+        "package scaffold",
         "package uninstall",
     ]),
     ...destinationRows("package", "package", "consolidation", "pm-tnud", [
@@ -170,9 +667,11 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "extension explore",
         "extension init",
         "extension install",
+        "extension list",
         "extension manage",
         "extension migrate",
         "extension reload",
+        "extension scaffold",
         "extension uninstall",
         "install",
         "packages",
@@ -186,9 +685,11 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "packages explore",
         "packages init",
         "packages install",
+        "packages list",
         "packages manage",
         "packages migrate",
         "packages reload",
+        "packages scaffold",
         "packages uninstall",
         "upgrade",
     ]),
@@ -210,7 +711,9 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "test-all",
         "validate",
     ]),
+    ...destinationRows("ops", "ops assurance", "consolidation", "pm-2tan", PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent }) => parent === "assurance").map(({ command }) => command)),
     ...destinationRows("plan", "plan", "target_noun", "pm-pbyu", ["plan"]),
+    ...destinationRows("plan", "plan", "target_noun", "pm-2tan", PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent }) => parent === "plan").map(({ command }) => command)),
     ...destinationRows("contracts", "contracts", "target_noun", "pm-pbyu", [
         "contracts",
     ]),
@@ -223,6 +726,15 @@ export const PM_COMMAND_DESTINATION_CONTRACTS = [
         "guide",
     ]),
 ];
+/** Exhaustive current command and positional-action signature table. */
+export const PM_COMMAND_POSITIONAL_CONTRACTS = [
+    ...new Set(PM_COMMAND_DESTINATION_CONTRACTS.map(({ command }) => command)),
+].map((command) => ({
+    command,
+    slots: resolvePmPositionalActionContract(command)?.slots ??
+        EXPLICIT_POSITIONAL_SLOTS.get(command) ??
+        [],
+}));
 /** Immutable grammar policy used by contracts and the CI gate. */
 export const PM_CLI_GRAMMAR_CONTRACT = {
     nouns: PM_CLI_GRAMMAR_NOUNS,
@@ -230,7 +742,111 @@ export const PM_CLI_GRAMMAR_CONTRACT = {
     scope_before_verb: true,
     visible_top_level_ceiling: 69,
     ceiling_raise_requires_pm_item: true,
+    positional_shape_budget: 21,
 };
+/** Report explicit positional entries that no destination command declares. */
+export function verifyExplicitPositionalSlotCensus(explicitCommands, destinationCommands) {
+    const destinations = new Set(destinationCommands);
+    return [...new Set(explicitCommands)]
+        .filter((command) => !destinations.has(command))
+        .map((command) => ({
+        code: "positional_signature_mismatch",
+        command,
+        detail: `Positional signature ${command} has no destination declaration.`,
+    }));
+}
+/** Return the semantic shape identity used by the positional-shape budget. */
+export function positionalShapeKey(slots) {
+    return slots
+        .map(({ required, variadic, value_kind: valueKind, polymorphic }) => `${required ? "r" : "o"}:${variadic ? "v" : "s"}:${valueKind}:${polymorphic ? "p" : "m"}`)
+        .join("|");
+}
+/** Return the exact canonical identity of an ordered positional signature. */
+export function positionalSignatureKey(slots) {
+    return slots
+        .map(({ name, required, variadic, value_kind: valueKind, polymorphic }) => `${name}:${required ? "r" : "o"}:${variadic ? "v" : "s"}:${valueKind}:${polymorphic ? "p" : "m"}`)
+        .join("|");
+}
+/** Return one deterministic finding for every repeated command path. */
+function duplicatePositionalSignatureFindings(contracts, surface) {
+    const counts = new Map();
+    for (const { command } of contracts) {
+        const normalized = normalizePositionalCommandPath(command);
+        counts.set(normalized, (counts.get(normalized) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count > 1)
+        .map(([command, count]) => ({
+        code: "positional_signature_mismatch",
+        command,
+        detail: `${count} ${surface} positional signatures exist for ${command}; exactly one is required.`,
+    }));
+}
+/** Compare independently observed Commander signatures with the SDK declaration. */
+export function verifyPmCommandPositionalContracts(observed, options = {}) {
+    const declared = options.declared ?? PM_COMMAND_POSITIONAL_CONTRACTS;
+    const positionalShapeBudget = options.positionalShapeBudget ??
+        PM_CLI_GRAMMAR_CONTRACT.positional_shape_budget;
+    const declaredByCommand = new Map(declared.map((contract) => [normalizePositionalCommandPath(contract.command), contract]));
+    const observedByCommand = new Map(observed.map((contract) => [normalizePositionalCommandPath(contract.command), contract]));
+    const findings = [
+        ...duplicatePositionalSignatureFindings(declared, "declared"),
+        ...duplicatePositionalSignatureFindings(observed, "observed"),
+        ...(options.declared === undefined
+            ? [
+                ...verifyExplicitPositionalSlotCensus(EXPLICIT_POSITIONAL_SLOTS.keys(), PM_COMMAND_DESTINATION_CONTRACTS.map(({ command }) => command)),
+                ...verifyExplicitPositionalSlotCensus(PM_POSITIONAL_ACTION_CONTRACTS.map(({ command }) => command), PM_COMMAND_DESTINATION_CONTRACTS.map(({ command }) => command)),
+            ]
+            : []),
+    ];
+    for (const contract of declaredByCommand.values()) {
+        const normalizedCommand = normalizePositionalCommandPath(contract.command);
+        const actual = observedByCommand.get(normalizedCommand);
+        if (!actual) {
+            findings.push({
+                code: "missing_observed_signature",
+                command: contract.command,
+                detail: `No observed positional signature exists for ${contract.command}.`,
+            });
+        }
+        else if (positionalSignatureKey(actual.slots) !==
+            positionalSignatureKey(contract.slots)) {
+            findings.push({
+                code: "positional_signature_mismatch",
+                command: contract.command,
+                detail: `Observed positional signature for ${contract.command} differs from its declared SDK contract: observed=${positionalSignatureKey(actual.slots) || "<none>"}; declared=${positionalSignatureKey(contract.slots) || "<none>"}.`,
+            });
+        }
+    }
+    for (const contract of observedByCommand.values()) {
+        if (!declaredByCommand.has(normalizePositionalCommandPath(contract.command))) {
+            findings.push({
+                code: "stale_observed_signature",
+                command: contract.command,
+                detail: `Observed positional signature ${contract.command} has no declaration.`,
+            });
+        }
+    }
+    const positionalShapeCount = new Set(declared.map(({ slots }) => positionalShapeKey(slots))).size;
+    if (positionalShapeCount > positionalShapeBudget) {
+        findings.push({
+            code: "positional_shape_budget_exceeded",
+            command: "*",
+            detail: `Distinct positional shape count ${positionalShapeCount} exceeds budget ${positionalShapeBudget}.`,
+        });
+    }
+    findings.sort((left, right) => left.command !== right.command
+        ? left.command.localeCompare(right.command)
+        : left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        declared_command_count: declared.length,
+        observed_command_count: observed.length,
+        positional_shape_count: positionalShapeCount,
+        positional_shape_budget: positionalShapeBudget,
+        findings,
+    };
+}
 function validateCommandDestinations(commands, destinationsByCommand, nounSet) {
     return commands.flatMap((command) => {
         const destinations = destinationsByCommand.get(command) ?? [];
@@ -342,4 +958,4 @@ export function verifyPmCliGrammar(commands, aliases = [], destinations = PM_COM
     };
 }
 //# sourceMappingURL=grammar-contracts.js.map
-//# debugId=b959d41a-c0b6-55fe-a426-0be073f0511c
+//# debugId=21495fd2-6abb-5a4f-965c-e7b9c8f87dff