@unbrained/pm-cli 2026.8.7 → 2026.8.8

package/dist/sdk/cli-contracts/command-exit-contracts.d.ts

@@ -0,0 +1,118 @@
+/** Stable numeric exit codes emitted by core pm commands. */
+export type PmCommandExitCode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+/** Effect-oriented outcome vocabulary shared by shells and structured output. */
+export type PmCommandExitOutcome = "effect" | "internal_failure" | "refused_input" | "refused_tracker_state" | "conflict" | "dependency_failed" | "no_effect" | "partial_effect";
+/** Meaning and success semantics for one stable process exit. */
+export interface PmCommandExitOutcomeContract {
+    /** Stable process exit visible without parsing stdout. */
+    exit_code: PmCommandExitCode;
+    /** Effect-oriented result independent of implementation details. */
+    outcome: PmCommandExitOutcome;
+    /** Whether the command completed its requested control flow successfully. */
+    success: boolean;
+    /** Concise operator-facing meaning. */
+    meaning: string;
+}
+/** Declared numeric exits for one core command path. */
+export interface PmCommandExitContract {
+    /** Normalized command path. */
+    command: string;
+    /** Exhaustive exits the command may emit. */
+    exit_codes: readonly PmCommandExitCode[];
+}
+/** One replay observation used to verify command exit declarations. */
+export interface PmCommandExitObservation {
+    /** Command path executed by the replay. */
+    command: string;
+    /** Process exit observed from the real command boundary. */
+    exit_code: number;
+    /** Stable replay case identifier for diagnostics. */
+    replay_id: string;
+}
+/** Drift report produced by exit-contract replay conformance. */
+export interface PmCommandExitConformanceReport {
+    /** Whether all declaration and observation checks passed. */
+    ok: boolean;
+    /** Expected commands without a declaration. */
+    missing_commands: string[];
+    /** Observations whose command or numeric exit is undeclared. */
+    undeclared_observations: PmCommandExitObservation[];
+    /** Declared numeric outcomes not reached anywhere in the replay corpus. */
+    unreachable_exit_codes: PmCommandExitCode[];
+}
+/** Canonical effect vocabulary for all stable CLI process exits. */
+export declare const PM_COMMAND_EXIT_OUTCOME_CONTRACTS: readonly [{
+    readonly exit_code: 0;
+    readonly outcome: "effect";
+    readonly success: true;
+    readonly meaning: "The requested operation completed with its intended effect.";
+}, {
+    readonly exit_code: 1;
+    readonly outcome: "internal_failure";
+    readonly success: false;
+    readonly meaning: "An unexpected runtime or internal failure prevented completion.";
+}, {
+    readonly exit_code: 2;
+    readonly outcome: "refused_input";
+    readonly success: false;
+    readonly meaning: "The invocation was refused because its input or composition was invalid.";
+}, {
+    readonly exit_code: 3;
+    readonly outcome: "refused_tracker_state";
+    readonly success: false;
+    readonly meaning: "The requested tracker, item, or resource was not present.";
+}, {
+    readonly exit_code: 4;
+    readonly outcome: "conflict";
+    readonly success: false;
+    readonly meaning: "Current state or concurrency prevented the requested effect.";
+}, {
+    readonly exit_code: 5;
+    readonly outcome: "dependency_failed";
+    readonly success: false;
+    readonly meaning: "A required dependency operation failed.";
+}, {
+    readonly exit_code: 6;
+    readonly outcome: "no_effect";
+    readonly success: true;
+    readonly meaning: "The request was valid and completed, but matched nothing to change.";
+}, {
+    readonly exit_code: 7;
+    readonly outcome: "partial_effect";
+    readonly success: true;
+    readonly meaning: "The request completed and changed some, but not all, selected targets.";
+}];
+/** Exhaustive core command exit declarations generated from the command registry. */
+export declare const PM_COMMAND_EXIT_CONTRACTS: readonly PmCommandExitContract[];
+/** Stable successful process exits, including machine-distinct effect states. */
+export declare const PM_SUCCESS_EXIT_CODES: readonly [0, 6, 7];
+/** Portable success effect reported by command result envelopes. */
+export type PmCommandEffect = "effect" | "no_effect" | "partial_effect" | "dependency_failed";
+/** Shell and envelope representation of one command effect or collected failure. */
+export interface PmCommandEffectReceipt {
+    /** Semantic effect observed after command execution. */
+    outcome: PmCommandEffect;
+    /** Stable shell exit paired with the effect. */
+    exit_code: 0 | 5 | 6 | 7;
+}
+/** Counts used to derive one bulk mutation's effect without parsing prose. */
+export interface PmBulkMutationEffectCounts {
+    /** Rows that completed the requested mutation. */
+    applied: number;
+    /** Rows deliberately left unchanged. */
+    skipped: number;
+    /** Rows whose attempted mutation failed. */
+    failed: number;
+    /** Explicit requested identifiers that did not exist. */
+    unmatched: number;
+}
+/** Return whether an exit represents a successful command outcome. */
+export declare function isPmSuccessfulExitCode(exitCode: number): boolean;
+/** Return whether an exit belongs to the declared pm process vocabulary. */
+export declare function isPmKnownExitCode(exitCode: number): exitCode is PmCommandExitCode;
+/** Resolve an exact command contract, falling back to its declared root path. */
+export declare function resolvePmCommandExitContract(commandPath: string): PmCommandExitContract | undefined;
+/** Verify command coverage, observed exits, and vocabulary reachability for a replay corpus. */
+export declare function analyzePmCommandExitConformance(observations: readonly PmCommandExitObservation[], expectedCommands?: readonly string[], contracts?: readonly PmCommandExitContract[]): PmCommandExitConformanceReport;
+/** Derive deterministic full, empty, partial, or failed semantics for a bulk mutation. */
+export declare function derivePmBulkMutationEffect(counts: PmBulkMutationEffectCounts): PmCommandEffectReceipt;

package/dist/sdk/cli-contracts/command-exit-contracts.js

@@ -0,0 +1,152 @@
+/**
+ * @module sdk/command-exit-contracts
+ *
+ * Declares shell-visible command outcomes and derives effect receipts shared by
+ * CLI, SDK, MCP, packages, telemetry, and conformance gates.
+ */
+
+!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]="5bbc21f0-f517-571a-8ecf-45f20f0e793d")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
+/** Canonical effect vocabulary for all stable CLI process exits. */
+export const PM_COMMAND_EXIT_OUTCOME_CONTRACTS = [
+    {
+        exit_code: EXIT_CODE.SUCCESS,
+        outcome: "effect",
+        success: true,
+        meaning: "The requested operation completed with its intended effect.",
+    },
+    {
+        exit_code: EXIT_CODE.GENERIC_FAILURE,
+        outcome: "internal_failure",
+        success: false,
+        meaning: "An unexpected runtime or internal failure prevented completion.",
+    },
+    {
+        exit_code: EXIT_CODE.USAGE,
+        outcome: "refused_input",
+        success: false,
+        meaning: "The invocation was refused because its input or composition was invalid.",
+    },
+    {
+        exit_code: EXIT_CODE.NOT_FOUND,
+        outcome: "refused_tracker_state",
+        success: false,
+        meaning: "The requested tracker, item, or resource was not present.",
+    },
+    {
+        exit_code: EXIT_CODE.CONFLICT,
+        outcome: "conflict",
+        success: false,
+        meaning: "Current state or concurrency prevented the requested effect.",
+    },
+    {
+        exit_code: EXIT_CODE.DEPENDENCY_FAILED,
+        outcome: "dependency_failed",
+        success: false,
+        meaning: "A required dependency operation failed.",
+    },
+    {
+        exit_code: EXIT_CODE.NO_EFFECT,
+        outcome: "no_effect",
+        success: true,
+        meaning: "The request was valid and completed, but matched nothing to change.",
+    },
+    {
+        exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        outcome: "partial_effect",
+        success: true,
+        meaning: "The request completed and changed some, but not all, selected targets.",
+    },
+];
+const STANDARD_COMMAND_EXIT_CODES = [
+    EXIT_CODE.SUCCESS,
+    EXIT_CODE.GENERIC_FAILURE,
+    EXIT_CODE.USAGE,
+    EXIT_CODE.NOT_FOUND,
+    EXIT_CODE.CONFLICT,
+    EXIT_CODE.DEPENDENCY_FAILED,
+];
+const EFFECT_AWARE_BULK_COMMANDS = new Set(["close-many", "update-many"]);
+/** Exhaustive core command exit declarations generated from the command registry. */
+export const PM_COMMAND_EXIT_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => ({
+    command,
+    exit_codes: EFFECT_AWARE_BULK_COMMANDS.has(command)
+        ? [
+            ...STANDARD_COMMAND_EXIT_CODES,
+            EXIT_CODE.NO_EFFECT,
+            EXIT_CODE.PARTIAL_EFFECT,
+        ]
+        : [...STANDARD_COMMAND_EXIT_CODES],
+}));
+const COMMAND_EXIT_CONTRACT_BY_PATH = new Map(PM_COMMAND_EXIT_CONTRACTS.map((contract) => [contract.command, contract]));
+/** Stable successful process exits, including machine-distinct effect states. */
+export const PM_SUCCESS_EXIT_CODES = [
+    EXIT_CODE.SUCCESS,
+    EXIT_CODE.NO_EFFECT,
+    EXIT_CODE.PARTIAL_EFFECT,
+];
+/** Return whether an exit represents a successful command outcome. */
+export function isPmSuccessfulExitCode(exitCode) {
+    return PM_SUCCESS_EXIT_CODES.includes(exitCode);
+}
+/** Return whether an exit belongs to the declared pm process vocabulary. */
+export function isPmKnownExitCode(exitCode) {
+    return PM_COMMAND_EXIT_OUTCOME_CONTRACTS.some((contract) => contract.exit_code === exitCode);
+}
+/** Resolve an exact command contract, falling back to its declared root path. */
+export function resolvePmCommandExitContract(commandPath) {
+    const normalized = commandPath
+        .trim()
+        .toLowerCase()
+        .split(/\s+/u)
+        .filter(Boolean)
+        .join(" ");
+    return (COMMAND_EXIT_CONTRACT_BY_PATH.get(normalized) ??
+        COMMAND_EXIT_CONTRACT_BY_PATH.get(normalized.split(" ")[0]));
+}
+/** Verify command coverage, observed exits, and vocabulary reachability for a replay corpus. */
+export function analyzePmCommandExitConformance(observations, expectedCommands = PM_CORE_COMMAND_NAMES, contracts = PM_COMMAND_EXIT_CONTRACTS) {
+    const contractsByCommand = new Map(contracts.map((contract) => [contract.command, contract]));
+    const missingCommands = expectedCommands.filter((command) => !contractsByCommand.has(command));
+    const undeclaredObservations = observations.filter((observation) => {
+        const contract = contractsByCommand.get(observation.command) ??
+            contractsByCommand.get(observation.command.split(" ")[0]);
+        return (contract === undefined ||
+            !contract.exit_codes.includes(observation.exit_code));
+    });
+    const observedExitCodes = new Set(observations.map((entry) => entry.exit_code));
+    const declaredExitCodes = new Set(contracts.flatMap((contract) => contract.exit_codes));
+    const unreachableExitCodes = [...declaredExitCodes]
+        .filter((exitCode) => !observedExitCodes.has(exitCode))
+        .sort((left, right) => left - right);
+    return {
+        ok: missingCommands.length === 0 &&
+            undeclaredObservations.length === 0 &&
+            unreachableExitCodes.length === 0,
+        missing_commands: missingCommands,
+        undeclared_observations: undeclaredObservations,
+        unreachable_exit_codes: unreachableExitCodes,
+    };
+}
+/** Derive deterministic full, empty, partial, or failed semantics for a bulk mutation. */
+export function derivePmBulkMutationEffect(counts) {
+    if (counts.applied === 0 && counts.failed > 0) {
+        return {
+            outcome: "dependency_failed",
+            exit_code: EXIT_CODE.DEPENDENCY_FAILED,
+        };
+    }
+    if (counts.applied === 0) {
+        return { outcome: "no_effect", exit_code: EXIT_CODE.NO_EFFECT };
+    }
+    if (counts.skipped > 0 || counts.failed > 0 || counts.unmatched > 0) {
+        return {
+            outcome: "partial_effect",
+            exit_code: EXIT_CODE.PARTIAL_EFFECT,
+        };
+    }
+    return { outcome: "effect", exit_code: EXIT_CODE.SUCCESS };
+}
+//# sourceMappingURL=command-exit-contracts.js.map
+//# debugId=5bbc21f0-f517-571a-8ecf-45f20f0e793d

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

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="0c81aa87-3ffb-5837-a3fa-eae5fb70eaf1")}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]="0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -120,7 +120,9 @@ const ACTION_FLAG_PARAMETER_OVERRIDES = {
     },
     files: { "--note": "addNote" },
     docs: { "--note": "addNote" },
-    notes: { "--file": "text" },
+    comments: { "--full-history": "full" },
+    notes: { "--file": "text", "--full-history": "full" },
+    learnings: { "--full-history": "full" },
     gc: { "--scope": "gcScope" },
     contracts: { "--action": "contractAction" },
     schema: {
@@ -364,4 +366,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=0c81aa87-3ffb-5837-a3fa-eae5fb70eaf1
+//# debugId=0fd4d2b0-725f-53ed-8b2b-2eeb19406cb7

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

@@ -7,7 +7,7 @@
  * 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]="8de867f9-e4d7-5c05-bae5-c3845a2280b7")}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]="932a6144-c4b4-5153-b8ff-0ef29e308bd0")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -222,6 +222,7 @@ export const COMMENTS_FLAG_CONTRACTS = [
     { flag: "--edit" },
     { flag: "--delete" },
     { flag: "--limit" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -243,6 +244,7 @@ export const NOTES_FLAG_CONTRACTS = [
     { flag: "--since" },
     { flag: "--event-type" },
     { flag: "--include-meta" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -251,6 +253,7 @@ export const NOTES_FLAG_CONTRACTS = [
 export const LEARNINGS_FLAG_CONTRACTS = [
     { flag: "--add", aliases: ["--learning"] },
     { flag: "--limit" },
+    { flag: "--full-history" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
@@ -1752,4 +1755,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=8de867f9-e4d7-5c05-bae5-c3845a2280b7
+//# debugId=932a6144-c4b4-5153-b8ff-0ef29e308bd0

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

@@ -13,6 +13,7 @@ import { type CliFlagInvocationContract } from "../flag-invocation-contracts.js"
 import { type PmCommandVisibilityTier } from "../agent-capability-contracts.js";
 import type { PmErrorCodeContract } from "../error-code-catalog.js";
 import { type PmCommandOutputEnvelopeContract } from "../output-contracts.js";
+import { type PmCommandExitContract, type PmCommandExitOutcomeContract } from "./command-exit-contracts.js";
 /** Documents the contracts command options payload exchanged by command, SDK, and package integrations. */
 export interface ContractsCommandOptions {
     /** Value that configures or reports action for this contract. */
@@ -152,6 +153,14 @@ export interface ContractsResult {
         budget: PmCommandOutputBudgetContract;
         envelope: PmCommandOutputEnvelopeContract;
     }>;
+    /** Stable outcome vocabulary and exhaustive per-command process exit sets. */
+    command_exit_contracts?: {
+        vocabulary: readonly PmCommandExitOutcomeContract[];
+        command_sets: Array<{
+            commands: string[];
+            exit_codes: PmCommandExitContract["exit_codes"];
+        }>;
+    };
 }
 type PmToolAction = (typeof PM_TOOL_ACTIONS)[number];
 /** Documents the contracts action availability payload exchanged by command, SDK, and package integrations. */
@@ -260,6 +269,7 @@ declare function attachCreateRequiredOptionContracts(schema: Record<string, unkn
 declare function readContractsSettings(pmRoot: string, readSettingsFn?: typeof readSettings): Promise<Awaited<ReturnType<typeof readSettings>>>;
 declare function buildCommandSummarySurface(commands: readonly string[]): CommandSummarySurface[];
 declare function buildCommandOutputContracts(commands: readonly string[]): NonNullable<ContractsResult["command_output_contracts"]>;
+declare function buildCommandExitContractGroups(commands: readonly string[]): NonNullable<ContractsResult["command_exit_contracts"]>["command_sets"];
 /** Implements run contracts for the public runtime surface of this module. */
 export declare function runContracts(options: ContractsCommandOptions, global: GlobalOptions): Promise<ContractsResult>;
 /** Public contract for test only contracts command, shared by SDK and presentation-layer consumers. */
@@ -269,6 +279,7 @@ export declare const _testOnlyContractsCommand: {
     buildExtensionActionSchemaBranch: typeof buildExtensionActionSchemaBranch;
     buildCommandSummarySurface: typeof buildCommandSummarySurface;
     buildCommandOutputContracts: typeof buildCommandOutputContracts;
+    buildCommandExitContractGroups: typeof buildCommandExitContractGroups;
     buildRuntimeFieldFlagContracts: typeof buildRuntimeFieldFlagContracts;
     collectActionContractDescriptors: typeof collectActionContractDescriptors;
     collectExtensionCommandContracts: typeof collectExtensionCommandContracts;

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

@@ -4,7 +4,7 @@
  * Implements the pm contracts command surface and its agent-facing runtime behavior.
  */
 
-!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]="36bb127d-7a88-5e0d-8296-3d74b9ceb813")}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]="adf76b7b-fc29-5b35-b33a-5ae008cbc8e7")}catch(e){}}();
 import { EXIT_CODE, SETTINGS_DEFAULTS, PmCliError, activateExtensions, getActiveExtensionRegistrations, loadExtensions, pathExists, commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, getSettingsPath, resolvePmRoot, readSettings, } from "../runtime-primitives.js";
 import { buildMcpToolContracts, } from "../../mcp/tool-definitions.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, ACTIVITY_FLAG_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EXTENSION_ACTIVATE_FLAG_CONTRACTS, EXTENSION_ADOPT_ALL_FLAG_CONTRACTS, EXTENSION_ADOPT_FLAG_CONTRACTS, EXTENSION_CATALOG_FLAG_CONTRACTS, EXTENSION_DEACTIVATE_FLAG_CONTRACTS, EXTENSION_DESCRIBE_FLAG_CONTRACTS, EXTENSION_DOCTOR_FLAG_CONTRACTS, EXTENSION_EXPLORE_FLAG_CONTRACTS, EXTENSION_FLAG_CONTRACTS, EXTENSION_INIT_FLAG_CONTRACTS, EXTENSION_INSTALL_FLAG_CONTRACTS, EXTENSION_MANAGE_FLAG_CONTRACTS, EXTENSION_MIGRATE_FLAG_CONTRACTS, EXTENSION_RELOAD_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PM_EXTENSION_CAPABILITY_CONTRACTS, PM_EXTENSION_POLICY_MODE_CONTRACTS, PM_EXTENSION_POLICY_SURFACE_CONTRACTS, PM_EXTENSION_SANDBOX_PROFILE_CONTRACTS, PM_EXTENSION_SERVICE_NAME_CONTRACTS, PM_EXTENSION_TRUST_MODE_CONTRACTS, PM_OUTPUT_DEGRADATION_STEPS, PLAN_FLAG_CONTRACTS, PM_CORE_COMMAND_NAMES, PM_TOOL_ACTIONS, PM_TOOL_PARAMETERS_SCHEMA, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, PROFILE_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, EVAL_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, NEXT_FLAG_CONTRACTS, SEARCH_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, compactFlagAliasContracts, resolvePmCommandOutputBudget, } from "../cli-contracts.js";
@@ -16,6 +16,7 @@ import { enrichCliFlagInvocationContracts, } from "../flag-invocation-contracts.
 import { resolvePmCommandVisibilityTier, } from "../agent-capability-contracts.js";
 import { PM_ERROR_CODE_CATALOG } from "../generated-error-code-catalog.js";
 import { resolvePmCommandOutputEnvelope, } from "../output-contracts.js";
+import { PM_COMMAND_EXIT_OUTCOME_CONTRACTS, resolvePmCommandExitContract, } from "./command-exit-contracts.js";
 const AGENT_BOOTSTRAP_FLAGS = new Map([
     [
         "claim",
@@ -1619,6 +1620,27 @@ function buildCommandOutputContracts(commands) {
         envelope: resolvePmCommandOutputEnvelope(command),
     }));
 }
+function buildCommandExitContractGroups(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const contract = resolvePmCommandExitContract(command);
+        const exitCodes = contract === undefined
+            ? [
+                EXIT_CODE.SUCCESS,
+                EXIT_CODE.GENERIC_FAILURE,
+                EXIT_CODE.USAGE,
+                EXIT_CODE.NOT_FOUND,
+                EXIT_CODE.CONFLICT,
+                EXIT_CODE.DEPENDENCY_FAILED,
+            ]
+            : contract.exit_codes;
+        const key = exitCodes.join(",");
+        const group = groups.get(key) ?? { commands: [], exit_codes: exitCodes };
+        group.commands.push(command);
+        groups.set(key, group);
+    }
+    return [...groups.values()];
+}
 function resolveExtensionCommandContracts(selection, runtime, outputCommands) {
     if (selection.selectedCommand) {
         return runtime.extensionContracts.filter((entry) => splitCommandPathAliases(entry.command).includes(selection.selectedCommand));
@@ -1791,6 +1813,10 @@ export async function runContracts(options, global) {
         result.error_codes = PM_ERROR_CODE_CATALOG;
         result.command_output_contracts =
             buildCommandOutputContracts(outputCommands);
+        result.command_exit_contracts = {
+            vocabulary: PM_COMMAND_EXIT_OUTCOME_CONTRACTS,
+            command_sets: buildCommandExitContractGroups(outputCommands),
+        };
     }
     return result;
 }
@@ -1801,6 +1827,7 @@ export const _testOnlyContractsCommand = {
     buildExtensionActionSchemaBranch,
     buildCommandSummarySurface,
     buildCommandOutputContracts,
+    buildCommandExitContractGroups,
     buildRuntimeFieldFlagContracts,
     collectActionContractDescriptors,
     collectExtensionCommandContracts,
@@ -1827,4 +1854,4 @@ export const _testOnlyContractsCommand = {
     toRuntimeShortFlagToken,
 };
 //# sourceMappingURL=runtime-contracts.js.map
-//# debugId=36bb127d-7a88-5e0d-8296-3d74b9ceb813
+//# debugId=adf76b7b-fc29-5b35-b33a-5ae008cbc8e7

package/dist/sdk/cli-contracts/tool-parameter-tables.js

@@ -4,7 +4,7 @@
  * Defines SDK command-contract metadata for Tool Parameter Tables.
  */
 
-!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]="57065b65-6582-5405-bf16-698023e204bf")}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]="35c4b819-02d6-582a-a7eb-fe3f4a4903d9")}catch(e){}}();
 import { PLAN_HARNESS_VALUES, PLAN_MODE_VALUES, PLAN_STEP_LINK_KIND_VALUES, PLAN_STEP_STATUS_VALUES, } from "../../types/index.js";
 import { PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS } from "../read-output-session.js";
 /** Public contract for pm tool parameter properties, shared by SDK and presentation-layer consumers. */
@@ -1804,12 +1804,25 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
             examples: [600, "1200"],
         },
     },
+    comments: {
+        full: {
+            description: "Return the complete post-mutation comment history instead of the bounded mutation receipt projection.",
+        },
+    },
     notes: {
+        full: {
+            description: "Return the complete post-mutation note history instead of the bounded mutation receipt projection.",
+        },
         since: {
             description: "Inclusive ISO 8601 creation timestamp lower bound for structured note event filtering.",
             examples: ["2026-01-01T00:00:00.000Z"],
         },
     },
+    learnings: {
+        full: {
+            description: "Return the complete post-mutation learning history instead of the bounded mutation receipt projection.",
+        },
+    },
     next: {
         tag: {
             description: "Only recommend items carrying this exact tag.",
@@ -1894,4 +1907,4 @@ export const PM_TOOL_ACTION_SCOPED_PARAMETER_METADATA = {
     },
 };
 //# sourceMappingURL=tool-parameter-tables.js.map
-//# debugId=57065b65-6582-5405-bf16-698023e204bf
+//# debugId=35c4b819-02d6-582a-a7eb-fe3f4a4903d9

package/dist/sdk/cli-contracts/tool-schema.d.ts

@@ -91,7 +91,7 @@ export interface PmActionToolInputSchemaOptions {
  */
 export declare function buildPmActionToolInputSchema(action: PmToolAction, options?: PmActionToolInputSchemaOptions): Record<string, unknown>;
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and the contract tests all bind to one constant instead of re-typing the `"4.0.2"` literal (pm-r9sz). Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.4.0";
+export declare const PM_TOOL_PARAMETERS_SCHEMA_VERSION: "4.4.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.

package/dist/sdk/cli-contracts/tool-schema.js

@@ -7,7 +7,7 @@
  * consumers from a single source of truth.
  */
 
-!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]="7fd02be1-d45b-5c2c-892a-4fbf8c1d5b9a")}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]="d9f01e68-6b54-5861-a4b5-ae40613c2047")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { TOOL_CREATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, } from "./tool-option-contracts.js";
@@ -811,6 +811,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "edit",
             "delete",
             "limit",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
     },
@@ -827,6 +828,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "since",
             "eventType",
             "includeMeta",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
         mutuallyExclusive: [
@@ -846,6 +848,7 @@ const PM_TOOL_ACTION_SCHEMA_CONTRACTS = {
             "edit",
             "delete",
             "limit",
+            "full",
             ...AUTHOR_MESSAGE_FORCE_PARAMETER_KEYS,
         ],
     },
@@ -1427,7 +1430,7 @@ function createLazyContractSchema(build) {
     });
 }
 /** Canonical version of the action-scoped strict MCP tool-parameters schema (`PM_TOOL_PARAMETERS_SCHEMA`). Exported as the single source of truth so the MCP server, the `pm contracts` command, SDK consumers, and the contract tests all bind to one constant instead of re-typing the `"4.0.2"` literal (pm-r9sz). Bump the patch/minor for additive, backward-compatible schema changes; bump the MAJOR for breaking changes — the major also drives the `$id` `tool-parameters-v{major}` slug, so the two never drift. */
-export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.4.0";
+export const PM_TOOL_PARAMETERS_SCHEMA_VERSION = "4.4.1";
 /**
  * Major component of {@link PM_TOOL_PARAMETERS_SCHEMA_VERSION}, used to build the
  * schema `$id` slug so a breaking version bump renames the document in lockstep.
@@ -1509,4 +1512,4 @@ export const _testOnlyCliContracts = {
     withFlagAliasMetadata,
 };
 //# sourceMappingURL=tool-schema.js.map
-//# debugId=7fd02be1-d45b-5c2c-892a-4fbf8c1d5b9a
+//# debugId=d9f01e68-6b54-5861-a4b5-ae40613c2047

package/dist/sdk/comments.d.ts

@@ -1,5 +1,6 @@
 import { type GlobalOptions } from "./runtime-primitives.js";
 import type { Comment } from "../types/index.js";
+import { type AnnotationMutationReceipt, type AnnotationOmissionReceipt } from "./annotations.js";
 /** Documents the comments command options payload exchanged by command, SDK, and package integrations. */
 export interface CommentsCommandOptions {
     /** Value that configures or reports add for this contract. */
@@ -16,6 +17,8 @@ export interface CommentsCommandOptions {
     limit?: string;
     /** Value that configures or reports include meta for this contract. */
     includeMeta?: boolean;
+    /** Return complete comment history after a mutation instead of a bounded receipt. */
+    fullHistory?: boolean;
     /** Value that configures or reports author for this contract. */
     author?: string;
     /** Human-readable explanation suitable for logs and agent-facing output. */
@@ -39,6 +42,10 @@ export interface CommentsResult {
     has_more?: boolean;
     /** Value that configures or reports limit for this contract. */
     limit?: number;
+    /** Mutation identity when this result changed the collection. */
+    mutation_receipt?: AnnotationMutationReceipt;
+    /** Declares whether older comments were withheld from a mutation response. */
+    omission_receipt?: AnnotationOmissionReceipt;
 }
 /** Implements run comments for the public runtime surface of this module. */
 export declare function runComments(id: string, options: CommentsCommandOptions, global: GlobalOptions): Promise<CommentsResult>;

package/dist/sdk/comments.js

@@ -4,7 +4,7 @@
  * Implements the pm comments command surface and its agent-facing runtime behavior.
  */
 
-!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]="500e83b0-28a8-58b1-a625-2d81eb245eb4")}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]="667218ac-866c-59b1-8309-18ad92434fca")}catch(e){}}();
 import { readFile } from "node:fs/promises";
 import { EXIT_CODE, PmCliError, createStdinTokenResolver, } from "./runtime-primitives.js";
 import { isErrnoError, parseAnnotationTextInput, runAnnotationCommand, } from "./annotations.js";
@@ -122,4 +122,4 @@ export async function runComments(id, options, global) {
     });
 }
 //# sourceMappingURL=comments.js.map
-//# debugId=500e83b0-28a8-58b1-a625-2d81eb245eb4
+//# debugId=667218ac-866c-59b1-8309-18ad92434fca