@unbrained/pm-cli 2026.8.4 → 2026.8.5

package/dist/core/item/item-format.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="c9225594-bc3b-5b07-8703-1debd1a98693")}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]="a4c22692-fe27-5178-bba2-190ac3f80628")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { isDeepStrictEqual } from "node:util";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, PLAN_STEP_STATUS_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
@@ -116,6 +116,12 @@ function assertItemMetadataCondition(condition, message) {
         validationError(message);
     }
 }
+function requireItemMetadataRecord(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        validationError(message);
+    }
+    return value;
+}
 function assertTimestampField(record, fieldName) {
     const rawValue = record[fieldName];
     assertItemMetadataCondition(typeof rawValue === "string", `${fieldName} must be a string`);
@@ -168,10 +174,7 @@ function assertRecurrenceExdates(value) {
     }
 }
 function assertValidRecurrenceRule(recurrence) {
-    assertItemMetadataCondition(typeof recurrence === "object" &&
-        recurrence !== null &&
-        !Array.isArray(recurrence), "event.recurrence must be an object");
-    const recurrenceRecord = recurrence;
+    const recurrenceRecord = requireItemMetadataRecord(recurrence, "event.recurrence must be an object");
     assertItemMetadataCondition(typeof recurrenceRecord.freq === "string", "event.recurrence.freq must be a string");
     const frequency = recurrenceRecord.freq.trim().toLowerCase();
     assertItemMetadataCondition(RECURRENCE_FREQUENCY_VALUES.includes(frequency), `event.recurrence.freq must be one of: ${RECURRENCE_FREQUENCY_VALUES.join(", ")}`);
@@ -261,10 +264,7 @@ function assertReminderEntries(record) {
     }
     assertItemMetadataCondition(Array.isArray(reminders), "reminders must be an array");
     for (const reminder of reminders) {
-        assertItemMetadataCondition(typeof reminder === "object" &&
-            reminder !== null &&
-            !Array.isArray(reminder), "reminders entries must be objects");
-        const reminderRecord = reminder;
+        const reminderRecord = requireItemMetadataRecord(reminder, "reminders entries must be objects");
         assertItemMetadataCondition(typeof reminderRecord.at === "string", "reminder.at must be a string");
         assertItemMetadataCondition(isTimestampLiteral(reminderRecord.at), "reminder.at must be a valid ISO timestamp");
         assertItemMetadataCondition(typeof reminderRecord.text === "string", "reminder.text must be a string");
@@ -294,8 +294,7 @@ function assertEventRecurrence(eventRecord) {
     }
 }
 function assertCalendarEventEntry(event) {
-    assertItemMetadataCondition(typeof event === "object" && event !== null && !Array.isArray(event), "events entries must be objects");
-    const eventRecord = event;
+    const eventRecord = requireItemMetadataRecord(event, "events entries must be objects");
     assertItemMetadataCondition(typeof eventRecord.start_at === "string", "event.start_at must be a string");
     assertItemMetadataCondition(isTimestampLiteral(eventRecord.start_at), "event.start_at must be a valid ISO timestamp");
     if (eventRecord.end_at !== undefined) {
@@ -337,10 +336,8 @@ function assertTypeOptionsField(record) {
     if (typeOptions === undefined) {
         return;
     }
-    assertItemMetadataCondition(typeof typeOptions === "object" &&
-        typeOptions !== null &&
-        !Array.isArray(typeOptions), "type_options must be an object");
-    for (const [optionKey, optionValue] of Object.entries(typeOptions)) {
+    const typeOptionsRecord = requireItemMetadataRecord(typeOptions, "type_options must be an object");
+    for (const [optionKey, optionValue] of Object.entries(typeOptionsRecord)) {
         assertItemMetadataCondition(optionKey.trim().length > 0, "type_options keys must be non-empty");
         assertItemMetadataCondition(typeof optionValue === "string", "type_options values must be strings");
         const optionText = optionValue;
@@ -386,10 +383,7 @@ function assertRuntimeUnknownItemMetadataFields(record, runtimeContext) {
     }
 }
 function assertValidItemMetadata(itemMetadata, runtimeContext) {
-    assertItemMetadataCondition(typeof itemMetadata === "object" &&
-        itemMetadata !== null &&
-        !Array.isArray(itemMetadata), "item metadata must be an object");
-    const record = itemMetadata;
+    const record = requireItemMetadataRecord(itemMetadata, "item metadata must be an object");
     const itemType = assertRequiredItemMetadataFields(record);
     assertStatusItemMetadataField(record, runtimeContext);
     assertPriorityAndTags(record);
@@ -1428,4 +1422,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=c9225594-bc3b-5b07-8703-1debd1a98693
+//# debugId=a4c22692-fe27-5178-bba2-190ac3f80628

package/dist/core/shared/constants.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]="8a44d44d-70c7-5321-b436-08aa6505a854")}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]="46d7e58b-d1b6-5f9d-86cb-76ca671ed127")}catch(e){}}();
 import { createDefaultExtensionGovernancePolicy } from "../extensions/extension-types.js";
 /**
  * Canonical default lifecycle status model and workflow role mapping.
@@ -442,6 +442,7 @@ export const TELEMETRY_ERROR_CATEGORY_BY_CODE = Object.freeze({
     lock_conflict: "conflict",
     terminal_state_conflict: "conflict",
     dependency_failed: "runtime",
+    init_gitignore_unwritable: "runtime",
     merge_git_config_unwritable: "runtime",
     command_failed: "runtime",
     unknown_error: "runtime",
@@ -474,4 +475,4 @@ export function resolveTelemetryErrorCategory(errorCode) {
     return "unknown";
 }
 //# sourceMappingURL=constants.js.map
-//# debugId=8a44d44d-70c7-5321-b436-08aa6505a854
+//# debugId=46d7e58b-d1b6-5f9d-86cb-76ca671ed127

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="827bddce-74c6-5b36-ae56-bf3b14625f82")}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]="f43e1170-e797-5a0c-b02e-d31e002ab275")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -684,4 +684,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=827bddce-74c6-5b36-ae56-bf3b14625f82
+//# debugId=f43e1170-e797-5a0c-b02e-d31e002ab275

package/dist/core/store/settings.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Settings.
  */
 
-!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]="9381a512-7436-5d2c-9667-3845b777b901")}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]="a434b9ea-4692-51c5-8761-0f1759fff394")}catch(e){}}();
 import { validateSettings } from "./settings-validator.js";
 import { runActiveOnReadHooks, runActiveOnWriteHooks, } from "../extensions/index.js";
 import { GOVERNANCE_PRESET_DEFAULTS, SETTINGS_DEFAULTS, } from "../shared/constants.js";
@@ -1298,4 +1298,4 @@ export const settingsStoreTestOnly = {
     selectedSettingsReadCacheSignaturesEqual,
 };
 //# sourceMappingURL=settings.js.map
-//# debugId=9381a512-7436-5d2c-9667-3845b777b901
+//# debugId=a434b9ea-4692-51c5-8761-0f1759fff394

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="fdff0dd1-1651-5f01-b822-60c075d14ad2")}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]="561c51e0-d7d9-5303-b116-443ad5037943")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -20,7 +20,7 @@ import { PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, } from "../sdk/agen
 import { commitItemMutations } from "../sdk/item-transaction.js";
 import { isRuntimeRecord } from "../sdk/runtime-input.js";
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
-import { parseAtomicMutationControls, validateItemMutationRows, } from "../sdk/structured-mutations.js";
+import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
 import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
@@ -99,18 +99,23 @@ const HANDLERS = {
     pm_run: (args) => runAction(args),
     pm_mutate: async (args) => {
         const transactionId = readRequiredString(args, "transactionId");
-        const mutations = validateItemMutationRows(args.mutations);
         const controls = parseAtomicMutationControls(args);
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const pmRoot = resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined);
+        const resolved = resolveItemMutationDocument(JSON.stringify({ schema_version: 1, mutations: args.mutations }), {
+            transactionId,
+            idPrefix: (await readSettings(pmRoot)).id_prefix,
+        });
+        const { mutations, references } = resolved;
         if (args.dryRun === true) {
             return {
                 transaction_id: transactionId,
                 dry_run: true,
                 mutation_count: mutations.length,
                 mutations,
+                references,
             };
         }
-        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
-        const pmRoot = resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined);
         const result = await runWithActiveExtensions({
             cwd: typeof args.cwd === "string" ? args.cwd : undefined,
             path: typeof args.path === "string" ? args.path : undefined,
@@ -127,6 +132,7 @@ const HANDLERS = {
             ...commitResult,
             transaction_id: committedTransactionId,
             mutation_count: mutations.length,
+            references,
         };
     },
     ...Object.fromEntries(Object.entries(NARROW_TOOL_ACTIONS).map(([tool, action]) => [
@@ -615,4 +621,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=fdff0dd1-1651-5f01-b822-60c075d14ad2
+//# debugId=561c51e0-d7d9-5303-b116-443ad5037943

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="ade687e6-6547-5a2f-818f-0ed06dce9de5")}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]="89c1ac6d-c217-54ea-8728-5a58762f86d9")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -254,8 +254,8 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_mutate",
-        description: "Apply an ordered create/update/close batch atomically through the public pm SDK. " +
-            "Use a stable transactionId to resume interrupted work; set dryRun=true to validate and preview without writes.",
+        description: "Apply an ordered create/update/close/release batch atomically through the public pm SDK. " +
+            "Create rows may declare ref and omit id; @ref forward references resolve deterministically from the stable transactionId. Set dryRun=true to validate and preview without writes.",
         inputSchema: objectSchema({
             transactionId: {
                 type: "string",
@@ -264,16 +264,23 @@ const RAW_TOOLS = [
             mutations: {
                 type: "array",
                 minItems: 1,
-                description: "Ordered rows shaped as {op:create|update|close,id,options?,reason?}.",
+                description: "Ordered rows shaped as {op:create|update|close|release,id?,ref?,options?,reason?}.",
                 items: {
                     type: "object",
                     properties: {
-                        op: { type: "string", enum: ["create", "update", "close"] },
+                        op: {
+                            type: "string",
+                            enum: ["create", "update", "close", "release"],
+                        },
                         id: idSchema,
+                        ref: {
+                            type: "string",
+                            description: "Batch-local create alias; its deterministic id can be referenced as @alias by any row.",
+                        },
                         reason: { type: "string" },
                         options: { type: "object" },
                     },
-                    required: ["op", "id"],
+                    required: ["op"],
                     additionalProperties: false,
                 },
             },
@@ -728,4 +735,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=ade687e6-6547-5a2f-818f-0ed06dce9de5
+//# debugId=89c1ac6d-c217-54ea-8728-5a58762f86d9

package/dist/sdk/cli-contracts/agent-output-contracts.d.ts

@@ -1,11 +1,3 @@
-/**
- * @module sdk/cli-contracts/agent-output-contracts
- *
- * Declares the agent-facing output budget vocabulary shared by CLI, SDK,
- * packages, contract discovery, and regression gates. The contracts describe
- * output policy without coupling package authors to pm's renderer.
- */
-import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
 /** Stable degradation stages applied when an output exceeds its token budget. */
 export declare const PM_OUTPUT_DEGRADATION_STEPS: readonly ["full", "compact", "brief", "summary", "counts"];
 /** Restricts deterministic output degradation stages. */
@@ -17,11 +9,16 @@ export type PmOutputBudgetClass = (typeof PM_OUTPUT_BUDGET_CLASSES)[number];
 /** Describes one command's default agent-output budget and degradation policy. */
 export interface PmCommandOutputBudgetContract {
     /** Canonical or compatibility command name. */
-    command: (typeof PM_CORE_COMMAND_NAMES)[number];
+    command: string;
     /** Workload class that selected the default ceiling. */
     budget_class: PmOutputBudgetClass;
     /** Default estimated-token ceiling for representative output. */
     default_max_estimated_tokens: number;
+    /** Encoding-specific ceilings generated from the workload-class default. */
+    default_max_estimated_tokens_by_format: Readonly<{
+        toon: number;
+        json: number;
+    }>;
     /** Ordered fallback projections, from richest to smallest. */
     degradation_ladder: readonly PmOutputDegradationStep[];
     /** Whether callers may explicitly request an unbounded result. */
@@ -29,6 +26,10 @@ export interface PmCommandOutputBudgetContract {
     /** Stable estimate used by gates and SDK consumers. */
     token_estimate: "ceil(utf8_bytes / 4)";
 }
+/** Infer the conservative workload class for a core or package command. */
+export declare function inferPmOutputBudgetClass(command: string): PmOutputBudgetClass;
+/** Build the generated default budget for a core or package command. */
+export declare function createPmCommandOutputBudget(command: string, budgetClass?: PmOutputBudgetClass): PmCommandOutputBudgetContract;
 /**
  * Declares one budget contract while preserving literal command metadata for
  * package-authored registries and test fixtures. Rejects ceilings that cannot
@@ -36,15 +37,14 @@ export interface PmCommandOutputBudgetContract {
  */
 export declare function definePmCommandOutputBudget<TContract extends PmCommandOutputBudgetContract>(contract: TContract): TContract;
 /** Public default budget contract for every built-in pm command. */
-export declare const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS: {
-    command: "search" | "create" | "update" | "list" | "context" | "release" | "schema" | "test" | "test-all" | "events" | "comments" | "notes" | "learnings" | "files" | "docs" | "copy" | "activity" | "history" | "item" | "extension" | "package" | "config" | "packages" | "event" | "list-all" | "list-draft" | "list-open" | "list-in-progress" | "list-blocked" | "list-closed" | "list-canceled" | "ctx" | "init" | "install" | "upgrade" | "focus" | "aggregate" | "get" | "next" | "eval" | "workspace" | "history-redact" | "history-repair" | "history-author-acknowledge" | "history-compact" | "merge" | "profile" | "plan" | "restore" | "update-many" | "close" | "close-many" | "delete" | "append" | "deps" | "graph" | "telemetry" | "health" | "validate" | "gc" | "stats" | "duplicates" | "contracts" | "claim" | "start-task" | "pause-task" | "close-task" | "meet" | "remind" | "help";
-    budget_class: "governance" | "mutation" | "read" | "discovery";
-    default_max_estimated_tokens: number;
-    degradation_ladder: readonly ["full", "compact", "brief", "summary", "counts"];
-    allows_unbounded_opt_out: true;
-    token_estimate: "ceil(utf8_bytes / 4)";
-}[];
+export declare const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS: PmCommandOutputBudgetContract[];
 /** Resolve the declared output budget for one built-in command. */
-export declare function resolvePmCommandOutputBudget(command: string): PmCommandOutputBudgetContract | null;
+export declare function resolvePmCommandOutputBudget(command: string, options: {
+    generateFallback: true;
+}): PmCommandOutputBudgetContract;
+/** Resolve a declared output budget without generating a package fallback. */
+export declare function resolvePmCommandOutputBudget(command: string, options?: {
+    generateFallback?: false;
+}): PmCommandOutputBudgetContract | null;
 /** Estimate conservative token usage from UTF-8 output bytes. */
 export declare function estimatePmOutputTokens(utf8Bytes: number): number;

package/dist/sdk/cli-contracts/agent-output-contracts.js

@@ -6,7 +6,7 @@
  * output policy without coupling package authors to pm's renderer.
  */
 
-!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]="7db1cef2-4ff1-5f62-ad68-88933e25d59b")}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]="23b3a820-f205-506b-9507-dbd60087f62e")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./enum-contracts.js";
 /** Stable degradation stages applied when an output exceeds its token budget. */
 export const PM_OUTPUT_DEGRADATION_STEPS = [
@@ -82,6 +82,39 @@ const DEFAULT_MAX_ESTIMATED_TOKENS = {
     discovery: 3_000,
     governance: 6_000,
 };
+const JSON_BUDGET_NUMERATOR = 3;
+const JSON_BUDGET_DENOMINATOR = 2;
+/** Infer the conservative workload class for a core or package command. */
+export function inferPmOutputBudgetClass(command) {
+    const [rootCommand = ""] = command.trim().split(/\s+/u);
+    return MUTATION_COMMANDS.has(rootCommand)
+        ? "mutation"
+        : DISCOVERY_COMMANDS.has(rootCommand)
+            ? "discovery"
+            : GOVERNANCE_COMMANDS.has(rootCommand)
+                ? "governance"
+                : "read";
+}
+/** Build the generated default budget for a core or package command. */
+export function createPmCommandOutputBudget(command, budgetClass = inferPmOutputBudgetClass(command)) {
+    const normalizedCommand = command.trim().replace(/\s+/gu, " ");
+    if (normalizedCommand.length === 0) {
+        throw new TypeError("command must be a non-empty command path");
+    }
+    const toonBudget = DEFAULT_MAX_ESTIMATED_TOKENS[budgetClass];
+    return definePmCommandOutputBudget({
+        command: normalizedCommand,
+        budget_class: budgetClass,
+        default_max_estimated_tokens: toonBudget,
+        default_max_estimated_tokens_by_format: {
+            toon: toonBudget,
+            json: Math.ceil((toonBudget * JSON_BUDGET_NUMERATOR) / JSON_BUDGET_DENOMINATOR),
+        },
+        degradation_ladder: PM_OUTPUT_DEGRADATION_STEPS,
+        allows_unbounded_opt_out: true,
+        token_estimate: "ceil(utf8_bytes / 4)",
+    });
+}
 /**
  * Declares one budget contract while preserving literal command metadata for
  * package-authored registries and test fixtures. Rejects ceilings that cannot
@@ -92,35 +125,30 @@ export function definePmCommandOutputBudget(contract) {
         contract.default_max_estimated_tokens <= 0) {
         throw new RangeError("default_max_estimated_tokens must be a positive safe integer");
     }
+    for (const [format, ceiling] of Object.entries(contract.default_max_estimated_tokens_by_format)) {
+        if (!Number.isSafeInteger(ceiling) || ceiling <= 0) {
+            throw new RangeError(`default_max_estimated_tokens_by_format.${format} must be a positive safe integer`);
+        }
+    }
     return contract;
 }
 /** Public default budget contract for every built-in pm command. */
-export const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => {
-    const budgetClass = MUTATION_COMMANDS.has(command)
-        ? "mutation"
-        : DISCOVERY_COMMANDS.has(command)
-            ? "discovery"
-            : GOVERNANCE_COMMANDS.has(command)
-                ? "governance"
-                : "read";
-    return definePmCommandOutputBudget({
-        command,
-        budget_class: budgetClass,
-        default_max_estimated_tokens: DEFAULT_MAX_ESTIMATED_TOKENS[budgetClass],
-        degradation_ladder: PM_OUTPUT_DEGRADATION_STEPS,
-        allows_unbounded_opt_out: true,
-        token_estimate: "ceil(utf8_bytes / 4)",
-    });
-});
+export const PM_COMMAND_OUTPUT_BUDGET_CONTRACTS = PM_CORE_COMMAND_NAMES.map((command) => createPmCommandOutputBudget(command));
 const OUTPUT_BUDGET_BY_COMMAND = new Map(PM_COMMAND_OUTPUT_BUDGET_CONTRACTS.map((contract) => [contract.command, contract]));
-/** Resolve the declared output budget for one built-in command. */
-export function resolvePmCommandOutputBudget(command) {
-    const [rootCommand] = command.trim().split(/\s+/u);
-    return OUTPUT_BUDGET_BY_COMMAND.get(rootCommand) ?? null;
+/** Implement built-in lookup with an opt-in generated package fallback. */
+export function resolvePmCommandOutputBudget(command, options = {}) {
+    const normalizedCommand = command.trim().replace(/\s+/gu, " ");
+    const [rootCommand] = normalizedCommand.split(" ");
+    const declared = OUTPUT_BUDGET_BY_COMMAND.get(rootCommand);
+    if (declared)
+        return { ...declared, command: normalizedCommand };
+    return options.generateFallback
+        ? createPmCommandOutputBudget(normalizedCommand)
+        : null;
 }
 /** Estimate conservative token usage from UTF-8 output bytes. */
 export function estimatePmOutputTokens(utf8Bytes) {
     return Math.ceil(Math.max(0, utf8Bytes) / 4);
 }
 //# sourceMappingURL=agent-output-contracts.js.map
-//# debugId=7db1cef2-4ff1-5f62-ad68-88933e25d59b
+//# debugId=23b3a820-f205-506b-9507-dbd60087f62e

package/dist/sdk/cli-contracts/commander-mutation-options.js

@@ -1,6 +1,6 @@
 /** Creates commander option registration contracts using the validated operation inputs. */
 
-!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]="c3f8fd9b-05f4-55b4-bceb-9300efac2cdb")}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]="b0f52c3d-091d-51db-a4c1-bb177414dd7f")}catch(e){}}();
 export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     {
         target: "title",
@@ -62,6 +62,30 @@ export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
         option: "--status, -s <value>",
         description: "Item status",
     },
+    {
+        target: "closeReason",
+        keys: ["closeReason", "close_reason"],
+        option: "--close-reason <value>",
+        description: "Close reason when creating directly in a terminal status",
+        aliasOptions: [
+            {
+                option: "--close_reason <value>",
+                description: "Alias for --close-reason",
+            },
+        ],
+    },
+    {
+        target: "completedAt",
+        keys: ["completedAt", "completed_at"],
+        option: "--completed-at <value>",
+        description: "Actual completion time for a terminal imported item",
+        aliasOptions: [
+            {
+                option: "--completed_at <value>",
+                description: "Alias for --completed-at",
+            },
+        ],
+    },
     {
         target: "priority",
         keys: ["priority"],
@@ -1019,4 +1043,4 @@ export const UPDATE_COMMANDER_STRING_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_
 /** Public contract for update commander repeatable option contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.filter((entry) => entry.repeatable === true).map((entry) => ({ target: entry.target, keys: entry.keys }));
 //# sourceMappingURL=commander-mutation-options.js.map
-//# debugId=c3f8fd9b-05f4-55b4-bceb-9300efac2cdb
+//# debugId=b0f52c3d-091d-51db-a4c1-bb177414dd7f

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

@@ -170,6 +170,8 @@ export declare const VALIDATE_FLAG_CONTRACTS: CliFlagContract[];
 export declare const CREATE_FLAG_CONTRACTS: CliFlagContract[];
 /** Atomic item-batch flags shared by contracts, help, and completions. */
 export declare const ITEM_MUTATE_FLAG_CONTRACTS: CliFlagContract[];
+/** Atomic item-completion flags shared by contracts, help, and completions. */
+export declare const ITEM_COMPLETE_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export declare const COPY_FLAG_CONTRACTS: CliFlagContract[];
 /** Public contract for focus flag contracts, shared by SDK and presentation-layer consumers. */

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]="768719fa-ae75-58fe-aa49-69da213c5eee")}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]="59bc9f68-0b43-5701-b3cf-1c1693a06d3a")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -1032,6 +1032,10 @@ export const CREATE_FLAG_CONTRACTS = [
     { flag: "--schedule-preset" },
     { flag: "--schedule_preset" },
     { short: "-s", flag: "--status" },
+    { flag: "--close-reason" },
+    { flag: "--close_reason" },
+    { flag: "--completed-at" },
+    { flag: "--completed_at" },
     { short: "-p", flag: "--priority" },
     { flag: "--tags", aliases: ["--tag"], list: true },
     // NOT list:true — these use Commander's repeatable collector. Marking them
@@ -1097,6 +1101,27 @@ export const ITEM_MUTATE_FLAG_CONTRACTS = [
     { flag: "--lock-wait-ms", value_name: "n" },
     { flag: "--author", value_name: "value" },
 ];
+/** Atomic item-completion flags shared by contracts, help, and completions. */
+export const ITEM_COMPLETE_FLAG_CONTRACTS = [
+    { flag: "--transaction-id", value_name: "value", required: true },
+    { flag: "--reason", value_name: "value" },
+    { flag: "--file", value_name: "value", repeatable: true },
+    { flag: "--doc", value_name: "value", repeatable: true },
+    { flag: "--test", value_name: "value", repeatable: true },
+    { flag: "--comment", value_name: "value", repeatable: true },
+    { flag: "--note", value_name: "value", repeatable: true },
+    { flag: "--learning", value_name: "value", repeatable: true },
+    { flag: "--resolution", value_name: "value" },
+    { flag: "--expected-result", value_name: "value" },
+    { flag: "--actual-result", value_name: "value" },
+    { flag: "--completed-at", value_name: "value" },
+    { flag: "--validate-close", value_name: "mode" },
+    { flag: "--lock-ttl-seconds", value_name: "n" },
+    { flag: "--lock-wait-ms", value_name: "n" },
+    { flag: "--dry-run" },
+    { flag: "--force" },
+    { flag: "--author", value_name: "value" },
+];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export const COPY_FLAG_CONTRACTS = [
     { flag: "--title" },
@@ -1573,6 +1598,7 @@ const SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND = new Map([
     ["upgrade", UPGRADE_FLAG_CONTRACTS],
     ["create", CREATE_FLAG_CONTRACTS],
     ["item mutate", ITEM_MUTATE_FLAG_CONTRACTS],
+    ["item complete", ITEM_COMPLETE_FLAG_CONTRACTS],
     ["copy", COPY_FLAG_CONTRACTS],
     ["focus", FOCUS_FLAG_CONTRACTS],
     ["aggregate", AGGREGATE_FLAG_CONTRACTS],
@@ -1719,4 +1745,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=768719fa-ae75-58fe-aa49-69da213c5eee
+//# debugId=59bc9f68-0b43-5701-b3cf-1c1693a06d3a

package/dist/sdk/cli-contracts/registration-helpers.js

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Registration Helpers.
  */
 
-!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]="b10305d7-7272-56a5-9178-3083e7cead7d")}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]="e520de00-0810-5356-9290-324cf1d3c133")}catch(e){}}();
 import { Option } from "commander";
 import { pathExists, refreshSearchArtifactsForMutation, shouldRunSearchRefreshInForeground, EXIT_CODE, PmCliError, printError, printResult, writeStdout, getSettingsPath, resolvePmRoot, readSettings, runActiveServiceOverride, setActiveCommandResult, } from "../runtime-primitives.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "../cli-contracts.js";
@@ -293,6 +293,8 @@ export function normalizeCreateOptions(commandOptions, options = {}) {
         createMode: readCreateString("createMode"),
         schedulePreset: readCreateString("schedulePreset"),
         status: readCreateString("status"),
+        closeReason: readCreateString("closeReason"),
+        completedAt: readCreateString("completedAt"),
         priority: readCreateString("priority"),
         tags: readCreateString("tags"),
         addTags: readCreateList("addTags"),
@@ -967,4 +969,4 @@ export const _testOnly = {
     collectMutationItemIds,
 };
 //# sourceMappingURL=registration-helpers.js.map
-//# debugId=b10305d7-7272-56a5-9178-3083e7cead7d
+//# debugId=e520de00-0810-5356-9290-324cf1d3c133

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

@@ -5,13 +5,14 @@
  */
 import { type GlobalOptions, type ExtensionRegistrationRegistry, type RegisteredExtensionCommandDefinition, type RegisteredExtensionFlagDefinitions, type RuntimeFieldRegistry, readSettings } from "../runtime-primitives.js";
 import { type McpToolContract } from "../../mcp/tool-definitions.js";
-import { PM_TOOL_ACTIONS, type CliFlagContract, type CommanderOptionAliasContract } from "../cli-contracts.js";
+import { PM_TOOL_ACTIONS, type CliFlagContract, type CommanderOptionAliasContract, type PmCommandOutputBudgetContract } from "../cli-contracts.js";
 import { type ListCommandName, type ListProjectionMode } from "../query/list.js";
 import { type PmContextIntentContract } from "../context-intent-contracts.js";
 import { type PmReadOutputSurfaceContract } from "../read-output-contracts.js";
 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";
 /** 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. */
@@ -146,6 +147,11 @@ export interface ContractsResult {
     read_output_dimensions?: readonly PmReadOutputSurfaceContract[];
     /** Exhaustive stable and provisional machine-readable failure vocabulary. */
     error_codes?: readonly PmErrorCodeContract[];
+    /** Format-aware budgets and envelope families for every active command. */
+    command_output_contracts?: Array<{
+        budget: PmCommandOutputBudgetContract;
+        envelope: PmCommandOutputEnvelopeContract;
+    }>;
 }
 type PmToolAction = (typeof PM_TOOL_ACTIONS)[number];
 /** Documents the contracts action availability payload exchanged by command, SDK, and package integrations. */
@@ -209,7 +215,7 @@ interface CommandSummarySurface {
     aliases?: string[];
     intent: string;
     flags?: string[];
-    default_max_estimated_tokens: number | null;
+    default_max_estimated_tokens: number;
 }
 declare function packageOwnedActionForCommand(command: string): string;
 declare function resolveActionCommandPath(action: PmToolAction): string | null;
@@ -253,6 +259,7 @@ declare function buildRuntimeFieldFlagContracts(fieldRegistry: RuntimeFieldRegis
 declare function attachCreateRequiredOptionContracts(schema: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>;
 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"]>;
 /** 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. */
@@ -261,6 +268,7 @@ export declare const _testOnlyContractsCommand: {
     attachCreateRequiredOptionContracts: typeof attachCreateRequiredOptionContracts;
     buildExtensionActionSchemaBranch: typeof buildExtensionActionSchemaBranch;
     buildCommandSummarySurface: typeof buildCommandSummarySurface;
+    buildCommandOutputContracts: typeof buildCommandOutputContracts;
     buildRuntimeFieldFlagContracts: typeof buildRuntimeFieldFlagContracts;
     collectActionContractDescriptors: typeof collectActionContractDescriptors;
     collectExtensionCommandContracts: typeof collectExtensionCommandContracts;