@unbrained/pm-cli 2026.8.18 → 2026.8.19

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

@@ -0,0 +1,55 @@
+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;
+}
+/** 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" | "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;
+    /** Stable ordered findings. */
+    findings: readonly PmFlagLexiconFinding[];
+}
+/** Build the canonical lexicon lazily from the same contracts as CLI and MCP. */
+export declare function listPmFlagLexicon(): readonly PmFlagLexiconEntry[];
+/** 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[]): 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,240 @@
+/**
+ * @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]="19215662-5a8c-5b91-bc97-8dbdc1daff02")}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;
+/** 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: contract.flag.slice(2),
+        flag: contract.flag,
+        aliases: Object.freeze([...(contract.aliases ?? [])]),
+        value_kind: (contract.repeatable
+            ? "list"
+            : 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;
+}
+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}.`,
+        });
+    }
+}
+/** Verify uniqueness, concept kind stability, alias safety, and flag budgets. */
+export function verifyPmFlagLexicon(entries = listPmFlagLexicon(), budgets = listPmCommandFlagBudgets()) {
+    const findings = [];
+    const canonicalOwners = new Map();
+    const conceptKinds = 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);
+        }
+    }
+    appendAliasCollisionFindings(entries, canonicalOwners, findings);
+    appendBudgetFindings(counts, budgets, 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,
+        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=19215662-5a8c-5b91-bc97-8dbdc1daff02

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

@@ -28,8 +28,53 @@ 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"];
@@ -37,7 +82,43 @@ export declare const PM_CLI_GRAMMAR_CONTRACT: {
     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. */