@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -25,7 +25,44 @@ export interface CliFlagInvocationContract extends CliFlagContract {
     /** Sentinel that redirects the argv value to stdin. */
     stdin_token?: "-";
 }
+/** Executable option arity observed from the registered Commander program. */
+export interface CliFlagArityObservation {
+    /** Canonical command path owning the option. */
+    command: string;
+    /** Long option spelling. */
+    flag: string;
+    /** Whether the option consumes a value token. */
+    takes_value: boolean;
+    /** Whether the consumed value is mandatory. */
+    value_required: boolean;
+    /** Whether repeated values accumulate. */
+    repeatable: boolean;
+}
+/** One machine-readable mismatch between declared and executable flag arity. */
+export interface CliFlagInvocationParityFinding {
+    /** Stable finding code. */
+    code: "duplicate_observation" | "missing_observation" | "takes_value_mismatch" | "value_required_mismatch" | "repeatable_mismatch" | "undeclared_observation";
+    /** Canonical command path. */
+    command: string;
+    /** Long option spelling. */
+    flag: string;
+    /** Human-readable mismatch detail. */
+    detail: string;
+}
+/** Complete parity receipt for one command's declared and executable flags. */
+export interface CliFlagInvocationParityReport {
+    /** Whether the two surfaces agree exactly. */
+    ok: boolean;
+    /** Number of declared invocation rows. */
+    declared_count: number;
+    /** Number of executable observations. */
+    observed_count: number;
+    /** Stable mismatch list. */
+    findings: CliFlagInvocationParityFinding[];
+}
 /** Enrich one vocabulary row with deterministic invocation and input-channel metadata. */
 export declare function enrichCliFlagInvocationContract(command: string, contract: CliFlagContract): CliFlagInvocationContract;
 /** Enrich a complete command flag table without mutating package-owned rows. */
 export declare function enrichCliFlagInvocationContracts(command: string, contracts: readonly CliFlagContract[]): CliFlagInvocationContract[];
+/** Compare generated invocation rows with independently observed executable arity. */
+export declare function verifyCliFlagInvocationParity(command: string, declarations: readonly CliFlagInvocationContract[], observations: readonly CliFlagArityObservation[]): CliFlagInvocationParityReport;

package/dist/sdk/flag-invocation-contracts.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]="0e2d29be-ff70-5e69-9bba-bef5ecd05fa1")}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]="0f857893-8441-54ad-af99-abaae9af864d")}catch(e){}}();
 const FLAG_DESCRIPTIONS = Object.freeze({
     "--body": "Set the item body.",
     "--body-file": "Read the item body from a file.",
@@ -38,23 +38,156 @@ const BOOLEAN_FLAG_PREFIXES = [
     "--check-",
     "--dry-run",
     "--explain",
-    "--filter-",
+    "--fail-",
+    "--fix-",
     "--full",
     "--has-",
     "--include-",
     "--json",
     "--no-",
-    "--only",
+    "--prune-",
     "--quiet",
+    "--refresh-",
     "--require-",
     "--runtime-only",
     "--schema-only",
+    "--skip-",
     "--stream",
     "--strict-",
     "--summary",
     "--today",
     "--verbose",
 ];
+const BOOLEAN_FLAG_NAMES = new Set([
+    "--activate",
+    "--active-only",
+    "--adopt",
+    "--adopt-all",
+    "--all",
+    "--all-actionable",
+    "--all-affected-ids",
+    "--all-day",
+    "--all-streams",
+    "--append-stable",
+    "--auto-fix",
+    "--auto-pm-context",
+    "--availability-only",
+    "--background",
+    "--brief",
+    "--by-assignee",
+    "--by-priority",
+    "--by-tag",
+    "--catalog",
+    "--claim",
+    "--clear",
+    "--clear-comments",
+    "--clear-criteria",
+    "--clear-deps",
+    "--clear-docs",
+    "--clear-events",
+    "--clear-files",
+    "--clear-learnings",
+    "--clear-notes",
+    "--clear-reminders",
+    "--clear-tests",
+    "--clear-type-options",
+    "--cli-only",
+    "--closed",
+    "--compact",
+    "--completion",
+    "--count",
+    "--counts",
+    "--deactivate",
+    "--declarative",
+    "--defaults",
+    "--describe",
+    "--diff",
+    "--doctor",
+    "--empty-body",
+    "--explore",
+    "--field-utilization",
+    "--filter-empty-body",
+    "--flags-only",
+    "--follow",
+    "--force",
+    "--global",
+    "--highlight",
+    "--hybrid",
+    "--id-only",
+    "--if-available",
+    "--ignore-global",
+    "--include_unparented",
+    "--infer",
+    "--init",
+    "--install",
+    "--isolated",
+    "--lean",
+    "--list",
+    "--local",
+    "--manage",
+    "--markdown",
+    "--metadata-coverage",
+    "--next",
+    "--normalize-provenance",
+    "--only",
+    "--only-last",
+    "--output-row-contract",
+    "--override-linked-pm-context",
+    "--packages-only",
+    "--past",
+    "--phrase-exact",
+    "--profile",
+    "--progress",
+    "--project",
+    "--promote-to-item-dep",
+    "--provenance",
+    "--provenance-summary",
+    "--raw",
+    "--ready-only",
+    "--ready_only",
+    "--rebuild",
+    "--recent",
+    "--reload",
+    "--repair",
+    "--replace-deps",
+    "--replace-docs",
+    "--replace-files",
+    "--replace-tests",
+    "--required",
+    "--required-on-create",
+    "--run",
+    "--runtime-probe",
+    "--save-baseline",
+    "--scaffold",
+    "--semantic",
+    "--shared-host-safe",
+    "--storage",
+    "--title-exact",
+    "--token-accounting",
+    "--trace",
+    "--tree",
+    "--unbounded",
+    "--uninstall",
+    "--validate-paths",
+    "--verify",
+    "--watch",
+    "--with-packages",
+]);
+const VALUE_FLAG_NAMES = new Set(["--only-index"]);
+const VALUE_COMMAND_FLAGS = new Set([
+    "activity:--stream",
+    "eval:--fail-under",
+    "validate:--fix-scope",
+]);
+const OPTIONAL_VALUE_COMMAND_FLAGS = new Set([
+    "activity:--stream",
+    "close:--validate-close",
+    "close-many:--validate-close",
+    "comments:--author",
+    "learnings:--author",
+    "notes:--author",
+]);
+const OPTIONAL_VALUE_FLAGS = new Set(["--regression"]);
 function resolveFlagInputSources(command, flag) {
     if (flag === "--stdin" || flag === "--stdin-json")
         return ["stdin"];
@@ -65,8 +198,9 @@ function resolveFlagInputSources(command, flag) {
     }
     return ["argv"];
 }
-function flagTakesValue(contract) {
-    const explicitlyValued = contract.value_name !== undefined ||
+function flagTakesValue(command, contract) {
+    const explicitlyValued = VALUE_COMMAND_FLAGS.has(`${command}:${contract.flag}`) ||
+        contract.value_name !== undefined ||
         contract.value_type === "string" ||
         contract.value_type === "number" ||
         contract.list === true ||
@@ -74,12 +208,18 @@ function flagTakesValue(contract) {
     const inferredBoolean = contract.value_type === "boolean" ||
         contract.flag === "--stdin" ||
         contract.flag === "--stdin-json" ||
+        (contract.flag.startsWith("--filter-") &&
+            (contract.flag.endsWith("-missing") ||
+                contract.flag.startsWith("--filter-has-") ||
+                contract.flag.startsWith("--filter-no-"))) ||
         BOOLEAN_FLAG_PREFIXES.some((prefix) => contract.flag.startsWith(prefix));
-    return explicitlyValued || !inferredBoolean;
+    return (explicitlyValued ||
+        VALUE_FLAG_NAMES.has(contract.flag) ||
+        (!BOOLEAN_FLAG_NAMES.has(contract.flag) && !inferredBoolean));
 }
 /** Enrich one vocabulary row with deterministic invocation and input-channel metadata. */
 export function enrichCliFlagInvocationContract(command, contract) {
-    const takesValue = flagTakesValue(contract);
+    const takesValue = flagTakesValue(command, contract);
     const inputSources = resolveFlagInputSources(command, contract.flag);
     const description = contract.description ??
         FLAG_DESCRIPTIONS[contract.flag] ??
@@ -88,7 +228,9 @@ export function enrichCliFlagInvocationContract(command, contract) {
         ...contract,
         description,
         takes_value: takesValue,
-        value_required: takesValue,
+        value_required: takesValue &&
+            !OPTIONAL_VALUE_FLAGS.has(contract.flag) &&
+            !OPTIONAL_VALUE_COMMAND_FLAGS.has(`${command}:${contract.flag}`),
         ...(takesValue ? { value_name: contract.value_name ?? "value" } : {}),
         value_type: takesValue ? (contract.value_type ?? "string") : "boolean",
         required: contract.required === true,
@@ -105,5 +247,72 @@ export function enrichCliFlagInvocationContract(command, contract) {
 export function enrichCliFlagInvocationContracts(command, contracts) {
     return contracts.map((contract) => enrichCliFlagInvocationContract(command, contract));
 }
+/** Compare generated invocation rows with independently observed executable arity. */
+export function verifyCliFlagInvocationParity(command, declarations, observations) {
+    const normalizedCommand = command.trim().toLowerCase();
+    const findings = [];
+    const observedByFlag = new Map();
+    let matchingObservationCount = 0;
+    for (const observation of observations) {
+        if (observation.command.trim().toLowerCase() !== normalizedCommand)
+            continue;
+        matchingObservationCount += 1;
+        if (observedByFlag.has(observation.flag)) {
+            findings.push({
+                code: "duplicate_observation",
+                command: normalizedCommand,
+                flag: observation.flag,
+                detail: `${normalizedCommand} ${observation.flag} was observed more than once.`,
+            });
+            continue;
+        }
+        observedByFlag.set(observation.flag, observation);
+    }
+    const declaredFlags = new Set(declarations.map(({ flag }) => flag));
+    for (const declaration of declarations) {
+        const observation = observedByFlag.get(declaration.flag);
+        if (!observation) {
+            findings.push({
+                code: "missing_observation",
+                command: normalizedCommand,
+                flag: declaration.flag,
+                detail: `${normalizedCommand} ${declaration.flag} has no executable option observation.`,
+            });
+            continue;
+        }
+        for (const [field, code] of [
+            ["takes_value", "takes_value_mismatch"],
+            ["value_required", "value_required_mismatch"],
+            ["repeatable", "repeatable_mismatch"],
+        ]) {
+            if (declaration[field] === observation[field])
+                continue;
+            findings.push({
+                code,
+                command: normalizedCommand,
+                flag: declaration.flag,
+                detail: `${normalizedCommand} ${declaration.flag} declares ${field}=${String(declaration[field])} but the executable option reports ${String(observation[field])}.`,
+            });
+        }
+    }
+    for (const observation of observedByFlag.values()) {
+        if (declaredFlags.has(observation.flag))
+            continue;
+        findings.push({
+            code: "undeclared_observation",
+            command: normalizedCommand,
+            flag: observation.flag,
+            detail: `${normalizedCommand} ${observation.flag} is executable but absent from invocation contracts.`,
+        });
+    }
+    findings.sort((left, right) => left.flag.localeCompare(right.flag) ||
+        left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        declared_count: declarations.length,
+        observed_count: matchingObservationCount,
+        findings,
+    };
+}
 //# sourceMappingURL=flag-invocation-contracts.js.map
-//# debugId=0e2d29be-ff70-5e69-9bba-bef5ecd05fa1
+//# debugId=0f857893-8441-54ad-af99-abaae9af864d

package/dist/sdk/generated/generated-error-code-catalog-part-1.js

@@ -1,6 +1,6 @@
 /** Generated partition 1 of the exhaustive error-code catalog. */
 
-!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]="29cde680-7551-51d1-9c5e-dd9d062d2397")}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]="145e12fa-839c-59da-840b-e2a0f3f13065")}catch(e){}}();
 export const PM_ERROR_CODE_CATALOG_PART_1 = [
     {
         code: "acceptance_criteria_mutation_conflict",
@@ -38,6 +38,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "acceptance_criteria_semicolon_forbidden",
         aliases: [],
     },
+    {
+        code: "accepted_rejected_value",
+        meaning: "Accepted rejected value condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "accepted_rejected_value",
+        aliases: [],
+    },
+    {
+        code: "alias_collision",
+        meaning: "Alias collision condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "alias_collision",
+        aliases: [],
+    },
     {
         code: "alias_target_missing",
         meaning: "Alias target missing condition.",
@@ -182,6 +206,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "body_file_unreadable",
         aliases: [],
     },
+    {
+        code: "budget_exceeded",
+        meaning: "Budget exceeded condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "budget_exceeded",
+        aliases: [],
+    },
     {
         code: "bundle_integrity_torn_install",
         meaning: "Bundle integrity torn install condition.",
@@ -482,6 +518,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "dependency_temporal_order_invalid",
         aliases: [],
     },
+    {
+        code: "duplicate_canonical_flag",
+        meaning: "Duplicate canonical flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "duplicate_canonical_flag",
+        aliases: [],
+    },
     {
         code: "duplicate_command",
         meaning: "Duplicate command condition.",
@@ -518,6 +566,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "duplicate_edge",
         aliases: [],
     },
+    {
+        code: "duplicate_observation",
+        meaning: "Duplicate observation condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/flag-invocation-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "duplicate_observation",
+        aliases: [],
+    },
+    {
+        code: "duplicate_probe",
+        meaning: "Duplicate probe condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "duplicate_probe",
+        aliases: [],
+    },
     {
         code: "duplicate_sweep_cost_limit",
         meaning: "Duplicate sweep cost limit condition.",
@@ -578,6 +650,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "duplicate_target_self",
         aliases: [],
     },
+    {
+        code: "empty_corpus",
+        meaning: "Empty corpus condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "empty_corpus",
+        aliases: [],
+    },
     {
         code: "empty_surface",
         meaning: "Empty surface condition.",
@@ -590,6 +674,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "empty_surface",
         aliases: [],
     },
+    {
+        code: "error_code_mismatch",
+        meaning: "Error code mismatch condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "error_code_mismatch",
+        aliases: [],
+    },
     {
         code: "event_cursor_query_mismatch",
         meaning: "Event cursor query mismatch condition.",
@@ -1094,6 +1190,30 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "improvement_observation_conflict",
         aliases: [],
     },
+    {
+        code: "incomplete_allowed_values",
+        meaning: "Incomplete allowed values condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "incomplete_allowed_values",
+        aliases: [],
+    },
+    {
+        code: "inconsistent_concept_kind",
+        meaning: "Inconsistent concept kind condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "inconsistent_concept_kind",
+        aliases: [],
+    },
     {
         code: "init_existing_settings_requires_force",
         meaning: "Init existing settings requires force condition.",
@@ -1476,6 +1596,18 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "invalid_workspace_snapshot_target",
         aliases: [],
     },
+    {
+        code: "item_already_active",
+        meaning: "Item already active condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/lifecycle/update.ts"],
+        emitting_commands: ["update"],
+        canonical_code: "item_already_active",
+        aliases: [],
+    },
     {
         code: "item_document_invalid",
         meaning: "Item document invalid condition.",
@@ -1704,6 +1836,78 @@ export const PM_ERROR_CODE_CATALOG_PART_1 = [
         canonical_code: "merge_decisions_unreviewed",
         aliases: [],
     },
+    {
+        code: "merge_git_config_unwritable",
+        meaning: "Merge git config unwritable condition.",
+        stability: "stable",
+        exit_code: 5,
+        class: "dependency_failed",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/install.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_git_config_unwritable",
+        aliases: [],
+    },
+    {
+        code: "merge_reconcile_discards_require_acceptance",
+        meaning: "Merge reconcile discards require acceptance condition.",
+        stability: "provisional",
+        exit_code: 4,
+        class: "conflict",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/reconcile.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_reconcile_discards_require_acceptance",
+        aliases: [],
+    },
+    {
+        code: "merge_root_not_found",
+        meaning: "Merge root not found condition.",
+        stability: "stable",
+        exit_code: 3,
+        class: "not_found",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/merge/install.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "merge_root_not_found",
+        aliases: [],
+    },
+    {
+        code: "missing_allowed_values",
+        meaning: "Missing allowed values condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/agent/refusal-closure.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_allowed_values",
+        aliases: [],
+    },
+    {
+        code: "missing_budget",
+        meaning: "Missing budget condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/flag-lexicon-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_budget",
+        aliases: [],
+    },
+    {
+        code: "missing_cli_flag",
+        meaning: "Missing cli flag condition.",
+        stability: "provisional",
+        exit_code: 1,
+        class: "generic_failure",
+        recovery: "Inspect the structured error guidance and retry the suggested command.",
+        sources: ["sdk/cli-contracts/tool-option-contracts.ts"],
+        emitting_commands: ["*"],
+        canonical_code: "missing_cli_flag",
+        aliases: [],
+    },
 ];
 //# sourceMappingURL=generated-error-code-catalog-part-1.js.map
-//# debugId=29cde680-7551-51d1-9c5e-dd9d062d2397
+//# debugId=145e12fa-839c-59da-840b-e2a0f3f13065