@unbrained/pm-cli 2026.8.4 → 2026.8.5

package/dist/sdk/graph/governance.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]="251ae2b0-10f4-528d-86b0-d224b126f8eb")}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]="76fa19c7-a421-5026-8de8-450285987c4e")}catch(e){}}();
 import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
@@ -195,7 +195,7 @@ function collectOrderingFindings(assembly, nodeStates, isBlocked, maxSampleSize)
             return predecessorState === undefined || !predecessorState.terminal;
         }))
         .map((state) => state.id);
-    appendFinding(findings, staleLifecycleBlocks, maxSampleSize, "stale_lifecycle_block", "warning", "A blocked lifecycle status must be backed by at least one open ordering predecessor.", (count) => `${count} status-blocked item(s) with no open blocker edge`, "Re-open the missing prerequisite as an edge, or move the item back to an active status.");
+    appendFinding(findings, staleLifecycleBlocks, maxSampleSize, "stale_lifecycle_block", "warning", "A blocked lifecycle status must be backed by at least one open ordering predecessor.", (count) => `${count} status-blocked item(s) with no open blocker edge`, 'Add a local blocker edge, declare an external blocker with --dep "id=<external-ref>,kind=blocked_by,source_kind=external", or move the item back to an active status.');
     return findings;
 }
 /** Format one duplicate-edge group as a compact deterministic evidence string. */
@@ -466,4 +466,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=251ae2b0-10f4-528d-86b0-d224b126f8eb
+//# debugId=76fa19c7-a421-5026-8de8-450285987c4e

package/dist/sdk/graph/remediation.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]="1f26594a-5843-556e-90b4-d733733f8828")}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]="9b8e22ad-6268-515d-994e-6b98a062ba93")}catch(e){}}();
 import { findRedundantRelationshipEdges } from "./analytics.js";
 import { auditWorkspaceRelationshipGraph, collectDuplicateRelationshipEdgeGroups, formatDuplicateEdgeGroup, } from "./governance.js";
 /** Per-finding-code operation template applied to every sampled subject. */
@@ -55,7 +55,7 @@ const FINDING_STEP_TEMPLATES = {
     stale_lifecycle_block: {
         op: "investigate",
         confidence: "medium",
-        rationale: "Re-open the missing prerequisite as an ordering edge, or move the item back to an active status; only the holder's owner knows which is true.",
+        rationale: 'Add a local ordering edge, declare an external blocker with --dep "id=<external-ref>,kind=blocked_by,source_kind=external", or move the item back to an active status; only the holder\'s owner knows which is true.',
     },
     isolated_active_node: {
         op: "investigate",
@@ -155,4 +155,4 @@ export function planRelationshipRemediation(assembly, options = {}) {
     };
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=1f26594a-5843-556e-90b4-d733733f8828
+//# debugId=9b8e22ad-6268-515d-994e-6b98a062ba93

package/dist/sdk/graph/run.js

@@ -11,7 +11,7 @@
  * queries in long-lived hosts are answered from the memoized snapshot.
  */
 
-!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]="ab1a6d49-f6e6-5a02-a948-8fd6e9be265a")}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]="0fbc54bf-3321-5c73-a351-5db01aab5544")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -423,9 +423,7 @@ function runGraphSlack(invocation) {
 /** Execute the structural-centrality ranking subcommand. */
 function runGraphCentrality(invocation) {
     const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
-    const result = computeRelationshipCentrality(invocation.assembly.graph, {
-        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
-    });
+    const result = computeRelationshipCentrality(invocation.assembly.graph, invocation.kinds === undefined ? {} : { kinds: invocation.kinds });
     const analysis = result.value;
     return {
         subcommand: "centrality",
@@ -454,9 +452,7 @@ function runGraphCentrality(invocation) {
 /** Execute the articulation-point and bridge (cut-structure) subcommand. */
 function runGraphArticulation(invocation) {
     const limit = invocation.limit ?? DEFAULT_SAMPLE_LIMIT;
-    const result = findRelationshipCutStructure(invocation.assembly.graph, {
-        ...(invocation.kinds === undefined ? {} : { kinds: invocation.kinds }),
-    });
+    const result = findRelationshipCutStructure(invocation.assembly.graph, invocation.kinds === undefined ? {} : { kinds: invocation.kinds });
     const { articulationPoints, bridges } = result.value;
     return {
         subcommand: "articulation",
@@ -717,4 +713,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=ab1a6d49-f6e6-5a02-a948-8fd6e9be265a
+//# debugId=0fbc54bf-3321-5c73-a351-5db01aab5544

package/dist/sdk/index.d.ts

@@ -45,7 +45,7 @@ export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export type { LocatedItem } from "../core/store/item-store.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageCatalogLinkMap, type PmPackageCatalogMediaMap, type PmPackageCatalogMetadata, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export type { CommanderOptionAliasContract, CommanderOptionRegistrationContract, } from "./cli-contracts.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_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_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, 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_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, definePmCommandOutputBudget, estimatePmOutputTokens, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_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_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, 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_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export type { CliFlagContract, OptionsFromContracts, PmActionSchemaContract, PmActionToolInputSchemaOptions, PmToolCustomFieldCollision, PmBulkMutationControlOptions, PmBulkMutationFilterOptions, PmCloseActionOptions, PmCloseManyActionOptions, PmCreateActionOptions, PmMutationAttributionOptions, PmOptionScalar, PmCommandOutputBudgetContract, PmOutputBudgetClass, PmOutputDegradationStep, PmUpdateActionOptions, PmUpdateManyActionOptions, PmExtensionCapabilityContract, PmExtensionPolicyModeContract, PmExtensionPolicySurfaceContract, PmExtensionSandboxProfileContract, PmExtensionServiceNameContract, PmExtensionTrustModeContract, PmToolAction, SdkCliActionParameterCoverage, SdkCliCompletenessContractSource, SdkCliParameterCoverageEntry, SdkCliParameterDisposition, ToolOptionFlagContract, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
@@ -83,6 +83,7 @@ export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
+export * from "./output-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";

package/dist/sdk/index.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="d5bccdd6-a532-570a-b545-f316abaaf70b")}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]="ee9b3579-e9c4-505d-9b38-3d3616757e64")}catch(e){}}();
 export { PM_COMMAND_VISIBILITY_CONTRACTS, PM_MCP_PROMPT_CONTRACTS, PM_MCP_RESOURCE_CONTRACTS, PM_MCP_TOOL_COMMAND_CONTRACTS, listPmCommandsForTier, listPmMcpToolsForProfile, renderPmCommandVisibilityMarkdown, resolvePmCommandVisibilityTier, } from "./agent-capability-contracts.js";
 export * from "./agent-session-context.js";
 export { isErrnoError, limitAnnotationEntries, parseAnnotationTextInput, readAnnotationEntries, resolveAnnotationInput, resolveAnnotationIndex, runAnnotationCommand, wrapOwnershipConflict, } from "./annotations.js";
@@ -44,7 +44,7 @@ export { PROFILE_SUBCOMMANDS, formatProfileApplyHuman, formatProfileLintHuman, f
 export * from "./extension-contracts.js";
 export { RESERVED_ITEM_FIELD_NAMES } from "../core/extensions/item-fields.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
-export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_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_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, 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_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, definePmCommandOutputBudget, estimatePmOutputTokens, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
+export { ACTIVITY_FLAG_CONTRACTS, ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, AGGREGATE_FLAG_CONTRACTS, APPEND_FLAG_CONTRACTS, CALENDAR_COMMANDER_STRING_OPTION_CONTRACTS, CALENDAR_FLAG_CONTRACTS, CLAIM_FLAG_CONTRACTS, CLOSE_ACTION_OPTION_KEYS, CLOSE_FLAG_CONTRACTS, CLOSE_MANY_FLAG_CONTRACTS, CLOSE_TASK_FLAG_CONTRACTS, COMMENTS_FLAG_CONTRACTS, COMPLETION_FLAG_CONTRACTS, CONFIG_FLAG_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_FLAG_CONTRACTS, CONTRACTS_FLAG_CONTRACTS, COPY_FLAG_CONTRACTS, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_FLAG_CONTRACTS, DELETE_FLAG_CONTRACTS, DEPS_FLAG_CONTRACTS, DOCS_FLAG_CONTRACTS, EVAL_FLAG_CONTRACTS, EVENT_FLAG_CONTRACTS, EVENTS_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_RELOAD_FLAG_CONTRACTS, EXTENSION_SCOPE_FLAG_CONTRACTS, EXTENSION_UNINSTALL_FLAG_CONTRACTS, FILES_FLAG_CONTRACTS, FOCUS_FLAG_CONTRACTS, GC_FLAG_CONTRACTS, GET_FLAG_CONTRACTS, GRAPH_FLAG_CONTRACTS, GLOBAL_FLAG_CONTRACTS, GUIDE_FLAG_CONTRACTS, HEALTH_FLAG_CONTRACTS, HISTORY_COMPACT_FLAG_CONTRACTS, HISTORY_FLAG_CONTRACTS, HISTORY_REDACT_FLAG_CONTRACTS, HISTORY_REPAIR_FLAG_CONTRACTS, HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS, INIT_FLAG_CONTRACTS, INSTALL_FLAG_CONTRACTS, ITEM_MUTATE_FLAG_CONTRACTS, ITEM_COMPLETE_FLAG_CONTRACTS, LEARNINGS_FLAG_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, LIST_FILTER_FLAG_CONTRACTS, MEET_FLAG_CONTRACTS, MERGE_FLAG_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_FLAG_CONTRACTS, NOTES_FLAG_CONTRACTS, PACKAGE_FLAG_CONTRACTS, PACKAGE_INIT_FLAG_CONTRACTS, PAUSE_TASK_FLAG_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, PLAN_FLAG_CONTRACTS, PM_COMMAND_OUTPUT_BUDGET_CONTRACTS, PM_CLI_ONLY_TOOL_ACTION_WAIVERS, PM_CORE_COMMAND_NAMES, PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS, 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_PROVIDER_TOOL_PARAMETERS_SCHEMA, PM_PROVIDER_TOOL_PARAMETERS_SCHEMA_VERSION, PM_TOOL_ACTIONS, analyzePmToolActionParity, PM_TOOL_ACTION_PARAMETER_CONTRACTS, PM_TOOL_PARAMETERS_SCHEMA, PM_TOOL_PARAMETERS_SCHEMA_MAJOR, PM_TOOL_PARAMETERS_SCHEMA_VERSION, PM_OUTPUT_BUDGET_CLASSES, PM_OUTPUT_DEGRADATION_STEPS, PROFILE_FLAG_CONTRACTS, REINDEX_FLAG_CONTRACTS, RELEASE_FLAG_CONTRACTS, REMIND_FLAG_CONTRACTS, RESTORE_FLAG_CONTRACTS, SCHEMA_FLAG_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_FLAG_CONTRACTS, START_TASK_FLAG_CONTRACTS, STATS_FLAG_CONTRACTS, DUPLICATES_FLAG_CONTRACTS, SUBCOMMAND_GLOBAL_FLAG_CONTRACTS, TELEMETRY_FLAG_CONTRACTS, TEST_ALL_FLAG_CONTRACTS, TEST_FLAG_CONTRACTS, TEST_RUNS_FLAG_CONTRACTS, TOOL_ACTIVITY_OPTION_CONTRACTS, TOOL_AGGREGATE_OPTION_CONTRACTS, TOOL_BULK_MUTATION_FILTER_OPTION_CONTRACT_SOURCE, TOOL_CALENDAR_OPTION_CONTRACTS, TOOL_CLOSE_MANY_FILTER_OPTION_CONTRACTS, TOOL_CONTEXT_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACTS, TOOL_CREATE_OPTION_CONTRACT_SOURCE, TOOL_DEPS_OPTION_CONTRACTS, TOOL_GRAPH_OPTION_CONTRACTS, TOOL_LIST_FILTER_OPTION_CONTRACTS, TOOL_SEARCH_FILTER_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACTS, TOOL_SHARED_CREATE_UPDATE_OPTION_CONTRACT_SOURCE, TOOL_UPDATE_MANY_FILTER_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACTS, TOOL_UPDATE_OPTION_CONTRACT_SOURCE, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_FLAG_CONTRACTS, UPDATE_MANY_FLAG_CONTRACTS, UPGRADE_FLAG_CONTRACTS, VALIDATE_FLAG_CONTRACTS, WORKSPACE_FLAG_CONTRACTS, buildPmActionToolInputSchema, PM_TOOL_RESERVED_CUSTOM_FIELD_PROPERTIES, compactFlagAliasContracts, createPmCommandOutputBudget, definePmCommandOutputBudget, estimatePmOutputTokens, inferPmOutputBudgetClass, analyzeSdkCliParameterCompleteness, isPmExtensionCapabilityContract, isPmExtensionPolicyModeContract, isPmExtensionPolicySurfaceContract, isPmExtensionServiceNameContract, isPmToolAction, hasSubcommandFlagContractsForCommand, readFirstStringFromCommanderOptions, readFirstValueFromCommanderOptions, readStringArrayFromCommanderOptions, resolveSubcommandFlagContractsForCommand, resolvePmCommandOutputBudget, resolvePmToolCustomFieldCollision, toCompletionFlagString, withFlagAliasMetadata, } from "./cli-contracts.js";
 export * from "./compose.js";
 export * from "./compile-cache.js";
 export * from "./context-relevance.js";
@@ -81,6 +81,7 @@ export * from "./pagination.js";
 export * from "./query/item-filter-options.js";
 export * from "./query/parsers.js";
 export * from "./output.js";
+export * from "./output-contracts.js";
 export * from "./relationship-analytics.js";
 export * from "./relationship-context.js";
 export * from "./relationship-history.js";
@@ -128,4 +129,4 @@ export * from "./governance.js";
 export * from "./query.js";
 export * from "./testing.js";
 //# sourceMappingURL=index.js.map
-//# debugId=d5bccdd6-a532-570a-b545-f316abaaf70b
+//# debugId=ee9b3579-e9c4-505d-9b38-3d3616757e64

package/dist/sdk/item-transaction.d.ts

@@ -33,8 +33,17 @@ export interface BulkItemCloseMutation {
     /** Close options forwarded to the public `close` runtime primitive. */
     options?: PmClientFullMutationOptions;
 }
+/** One atomic claim release inside a bulk mutation batch. */
+export interface BulkItemReleaseMutation {
+    /** Discriminates the claim-release operation. */
+    op: "release";
+    /** Target item id. */
+    id: string;
+    /** Release options forwarded to the public `release` runtime primitive. */
+    options?: PmClientFullMutationOptions;
+}
 /** Union of the item mutations a bulk transaction batch can carry. */
-export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation;
+export type BulkItemMutation = BulkItemCreateMutation | BulkItemUpdateMutation | BulkItemCloseMutation | BulkItemReleaseMutation;
 /** Options accepted by the bulk item-mutation transaction helper. */
 export interface CommitItemMutationsOptions {
     /** Tracker root that owns the journal and workspace-wide writer lock. */
@@ -80,18 +89,20 @@ interface LocatedItemSnapshot {
     id: string;
     closedAt: string | undefined;
     updatedAt: string;
+    assignee: string | undefined;
+    claimPrincipal: string | undefined;
 }
 /** Read one item's transaction-relevant fields, mapping not-found to undefined. */
 declare function readItemSnapshot(pmRoot: string, id: string): Promise<LocatedItemSnapshot | undefined>;
-/** Derive a journal-safe step id from one mutation's position and target. */
+/** Derive a journal-safe step id bound to position, target, and payload. */
 declare function deriveStepId(mutation: BulkItemMutation, index: number): string;
 /** Build the durable history-message marker for one bulk mutation phase. */
 declare function bulkHistoryMarker(transactionId: string, stepId: string, phase: "apply" | "compensate"): string;
 /**
- * Report whether an update step's forward mutation is durably applied. Updates
- * cannot be inferred from field values (a moving target), so the applied apply
- * marker in the item's immutable history is the source of truth; a later
- * compensate marker means the mutation was rolled back and must re-apply.
+ * Report whether a step's forward mutation is durably applied. Mutable item
+ * fields cannot prove transaction ownership, so the apply marker in immutable
+ * history is the source of truth; a later compensation marker means the
+ * mutation was rolled back and must re-apply.
  */
 declare function isUpdateMarkerApplied(pmRoot: string, canonicalId: string, transactionId: string, stepId: string): Promise<boolean>;
 /** Idempotently restore an item to its captured pre-mutation version. */
@@ -119,6 +130,40 @@ declare function buildCreateStep(config: {
  * interrupted batches resumable across processes and agents.
  */
 export declare function commitItemMutations(options: CommitItemMutationsOptions): Promise<CommitItemMutationsResult>;
+/** Options for completing one item as a single atomic SDK transaction. */
+export interface CommitItemCompletionOptions {
+    /** Tracker root that owns the item and transaction journal. */
+    pmRoot: string;
+    /** Stable idempotency key for the composed completion. */
+    transactionId: string;
+    /** Attributable actor for evidence, closure, and claim release. */
+    author: string;
+    /** Item being completed. */
+    id: string;
+    /** Durable close reason. */
+    reason: string;
+    /** Evidence and linked-resource updates recorded before closure. */
+    evidence?: PmClientFullMutationOptions;
+    /** Structured closure fields and validation policy. */
+    closeOptions?: PmClientFullMutationOptions;
+    /** Claim-release controls. */
+    releaseOptions?: PmClientFullMutationOptions;
+    /** Workspace transaction lock lifetime in seconds. */
+    lockTtlSeconds?: number;
+    /** Maximum time to wait for the workspace transaction lock. */
+    lockWaitMs?: number;
+    /** Optional transition observer used by telemetry and crash tests. */
+    onTransition?: CommitWorkspaceTransactionOptions["onTransition"];
+}
+/** Build the ordered mutation sequence used by atomic item completion. */
+export declare function buildItemCompletionMutations(options: Pick<CommitItemCompletionOptions, "id" | "reason" | "evidence" | "closeOptions" | "releaseOptions">): BulkItemMutation[];
+/**
+ * Record evidence, close an item, and release its claim as one compensating
+ * transaction. A failure restores the exact pre-completion item version, so
+ * callers never observe the protocol's otherwise possible half-finished
+ * states through a committed result.
+ */
+export declare function commitItemCompletion(options: CommitItemCompletionOptions): Promise<CommitItemMutationsResult>;
 /** Public contract for test only item transaction internals, shared with white-box specs. */
 export declare const _testOnlyItemTransaction: {
     buildCreateStep: typeof buildCreateStep;

package/dist/sdk/item-transaction.js

@@ -6,12 +6,14 @@
  * with correct-by-construction inspection and compensation wiring.
  */
 
-!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]="0b22a2a8-d626-54e1-8f14-670e651a6eb2")}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]="ed638747-7a72-5332-87fc-c82088457b91")}catch(e){}}();
+import crypto from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
+import { stableStringify } from "../core/shared/serialization.js";
 import { readHistoryEntries } from "./history-read.js";
-import { close, create, deleteItem, get, restore, update, } from "./runtime.js";
+import { close, create, deleteItem, get, release, restore, update, } from "./runtime.js";
 import { commitWorkspaceTransaction, } from "./workspace-transaction.js";
 /** Read one item's transaction-relevant fields, mapping not-found to undefined. */
 async function readItemSnapshot(pmRoot, id) {
@@ -22,18 +24,29 @@ async function readItemSnapshot(pmRoot, id) {
             id: item.id,
             closedAt: item.closed_at,
             updatedAt: item.updated_at,
+            assignee: item.assignee,
+            claimPrincipal: item.claim_principal,
         };
     }
     catch (error) {
-        if (error instanceof PmCliError &&
-            error.exitCode === EXIT_CODE.NOT_FOUND) {
+        if (error instanceof PmCliError && error.exitCode === EXIT_CODE.NOT_FOUND) {
             return undefined;
         }
         throw error;
     }
 }
-/** Derive a journal-safe step id from one mutation's position and target. */
+/** Derive a journal-safe step id bound to position, target, and payload. */
 function deriveStepId(mutation, index) {
+    const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
+    const fingerprint = crypto
+        .createHash("sha256")
+        .update(stableStringify(mutation))
+        .digest("hex")
+        .slice(0, 12);
+    return `${index + 1}-${mutation.op}-${sanitizedTarget}-${fingerprint}`;
+}
+/** Derive the stable public outcome key without exposing journal internals. */
+function deriveOutcomeKey(mutation, index) {
     const sanitizedTarget = mutation.id.replaceAll(/[^a-zA-Z0-9._-]/gu, "_");
     return `${index + 1}-${mutation.op}-${sanitizedTarget}`;
 }
@@ -42,10 +55,10 @@ function bulkHistoryMarker(transactionId, stepId, phase) {
     return `bulk-item-transaction ${transactionId} ${stepId} ${phase}`;
 }
 /**
- * Report whether an update step's forward mutation is durably applied. Updates
- * cannot be inferred from field values (a moving target), so the applied apply
- * marker in the item's immutable history is the source of truth; a later
- * compensate marker means the mutation was rolled back and must re-apply.
+ * Report whether a step's forward mutation is durably applied. Mutable item
+ * fields cannot prove transaction ownership, so the apply marker in immutable
+ * history is the source of truth; a later compensation marker means the
+ * mutation was rolled back and must re-apply.
  */
 async function isUpdateMarkerApplied(pmRoot, canonicalId, transactionId, stepId) {
     const entries = await readHistoryEntries(path.join(pmRoot, "history", `${canonicalId}.jsonl`), canonicalId);
@@ -163,7 +176,13 @@ function buildCloseStep(config, mutation, stepId) {
         // fight legitimate prior closure, and recovery must adopt completed work.
         async inspect() {
             const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
-            if (snapshot?.closedAt === undefined) {
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
+                return { state: "applied", result: { id: snapshot.id, op: "close" } };
+            }
+            if (snapshot.closedAt === undefined) {
                 return { state: "pending" };
             }
             return { state: "applied", result: { id: snapshot.id, op: "close" } };
@@ -172,7 +191,11 @@ function buildCloseStep(config, mutation, stepId) {
             return prepareRestoreCompensation(config.pmRoot, mutation);
         },
         async apply() {
-            const closed = await close(mutation.id, mutation.reason, { ...mutation.options, author: config.author }, { pmRoot: config.pmRoot });
+            const closed = await close(mutation.id, mutation.reason, {
+                ...mutation.options,
+                author: config.author,
+                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
+            }, { pmRoot: config.pmRoot });
             const closedItem = closed.item;
             return { id: String(closedItem.id), op: "close" };
         },
@@ -181,16 +204,54 @@ function buildCloseStep(config, mutation, stepId) {
         },
     };
 }
+/** Build the workspace-transaction step for one claim release. */
+function buildReleaseStep(config, mutation, stepId) {
+    return {
+        id: stepId,
+        async inspect() {
+            const snapshot = await readItemSnapshot(config.pmRoot, mutation.id);
+            if (snapshot === undefined) {
+                return { state: "pending" };
+            }
+            if (await isUpdateMarkerApplied(config.pmRoot, snapshot.id, config.transactionId, stepId)) {
+                return { state: "applied", result: { id: snapshot.id, op: "release" } };
+            }
+            if (snapshot.assignee !== undefined ||
+                snapshot.claimPrincipal !== undefined) {
+                return { state: "pending" };
+            }
+            return { state: "applied", result: { id: snapshot.id, op: "release" } };
+        },
+        async prepareCompensation() {
+            return prepareRestoreCompensation(config.pmRoot, mutation);
+        },
+        async apply() {
+            const released = await release(mutation.id, {
+                ...mutation.options,
+                author: config.author,
+                message: bulkHistoryMarker(config.transactionId, stepId, "apply"),
+            }, { pmRoot: config.pmRoot });
+            const releasedItem = released.item;
+            return { id: String(releasedItem.id), op: "release" };
+        },
+        async compensate(data) {
+            await compensateByRestore(config, mutation.id, stepId, data);
+        },
+    };
+}
 /** Convert one validated bulk mutation into its workspace-transaction step. */
 function buildStepForMutation(config, mutation, index) {
     const stepId = deriveStepId(mutation, index);
-    if (mutation.op === "create") {
-        return buildCreateStep(config, mutation, stepId);
+    switch (mutation.op) {
+        case "create":
+            return buildCreateStep(config, mutation, stepId);
+        case "update":
+            return buildUpdateStep(config, mutation, stepId);
+        case "close":
+            return buildCloseStep(config, mutation, stepId);
+        case "release":
+            return buildReleaseStep(config, mutation, stepId);
     }
-    if (mutation.op === "update") {
-        return buildUpdateStep(config, mutation, stepId);
-    }
-    return buildCloseStep(config, mutation, stepId);
 }
 /** Reject malformed bulk mutation rows before any journal or lock work. */
 function assertValidBulkMutation(mutation, index) {
@@ -199,8 +260,8 @@ function assertValidBulkMutation(mutation, index) {
         Array.isArray(mutation)) {
         throw new TypeError(`Bulk mutation ${index + 1} must be an object`);
     }
-    if (!["create", "update", "close"].includes(mutation.op)) {
-        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, or close`);
+    if (!["create", "update", "close", "release"].includes(mutation.op)) {
+        throw new TypeError(`Bulk mutation ${index + 1} op must be create, update, close, or release`);
     }
     if (typeof mutation.id !== "string" || mutation.id.trim().length === 0) {
         throw new TypeError(`Bulk mutation ${index + 1} requires a non-empty id`);
@@ -255,10 +316,13 @@ export async function commitItemMutations(options) {
             : { onTransition: options.onTransition }),
     });
     const results = {};
-    for (const [stepId, value] of Object.entries(committed.results)) {
+    for (const [index, mutation] of mutations.entries()) {
+        const stepId = deriveStepId(mutation, index);
+        const value = committed.results[stepId];
         // Journal values round-trip this module's own step outputs, which are
         // always {id, op} objects — the cast restores the concrete outcome shape.
-        results[stepId] = value;
+        results[deriveOutcomeKey(mutation, index)] =
+            value;
     }
     return {
         transactionId: committed.transactionId,
@@ -267,6 +331,52 @@ export async function commitItemMutations(options) {
         results,
     };
 }
+/** Build the ordered mutation sequence used by atomic item completion. */
+export function buildItemCompletionMutations(options) {
+    const mutations = [];
+    if (options.evidence !== undefined &&
+        Object.keys(options.evidence).length > 0) {
+        mutations.push({ op: "update", id: options.id, options: options.evidence });
+    }
+    mutations.push({
+        op: "close",
+        id: options.id,
+        reason: options.reason,
+        ...(options.closeOptions === undefined
+            ? {}
+            : { options: options.closeOptions }),
+    }, {
+        op: "release",
+        id: options.id,
+        ...(options.releaseOptions === undefined
+            ? {}
+            : { options: options.releaseOptions }),
+    });
+    return mutations;
+}
+/**
+ * Record evidence, close an item, and release its claim as one compensating
+ * transaction. A failure restores the exact pre-completion item version, so
+ * callers never observe the protocol's otherwise possible half-finished
+ * states through a committed result.
+ */
+export function commitItemCompletion(options) {
+    return commitItemMutations({
+        pmRoot: options.pmRoot,
+        transactionId: options.transactionId,
+        author: options.author,
+        mutations: buildItemCompletionMutations(options),
+        ...(options.lockTtlSeconds === undefined
+            ? {}
+            : { lockTtlSeconds: options.lockTtlSeconds }),
+        ...(options.lockWaitMs === undefined
+            ? {}
+            : { lockWaitMs: options.lockWaitMs }),
+        ...(options.onTransition === undefined
+            ? {}
+            : { onTransition: options.onTransition }),
+    });
+}
 /** Public contract for test only item transaction internals, shared with white-box specs. */
 export const _testOnlyItemTransaction = {
     buildCreateStep,
@@ -277,4 +387,4 @@ export const _testOnlyItemTransaction = {
     readItemSnapshot,
 };
 //# sourceMappingURL=item-transaction.js.map
-//# debugId=0b22a2a8-d626-54e1-8f14-670e651a6eb2
+//# debugId=ed638747-7a72-5332-87fc-c82088457b91

package/dist/sdk/lifecycle/create.d.ts

@@ -20,6 +20,10 @@ export interface CreateCommandOptions extends MutationMetadataCommandOptions, Sh
     type?: string;
     /** Lifecycle state reported for status. */
     status?: string;
+    /** Author-controlled reason when creating directly in a terminal status. */
+    closeReason?: string;
+    /** Actual completion time when importing an already-completed item. */
+    completedAt?: string;
     /** Value that configures or reports priority for this contract. */
     priority?: string | number;
     /** Value that configures or reports tags for this contract. */

package/dist/sdk/lifecycle/create.js

@@ -4,9 +4,9 @@
  * Implements the pm create 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]="5f01dc2b-6239-5724-aa36-8f81b580b76a")}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]="93dc76a3-f205-5a44-85bd-5a6fad80c8d4")}catch(e){}}();
 import { pathExists, removeFileIfExists, writeFileAtomic, appendHistoryEntry, createHistoryEntry, generateItemId, normalizeItemId, canonicalDocument, normalizeItemMetadata, serializeItemDocument, assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, validateSprintOrReleaseValue, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, resolvePriority, getFocusedItem, normalizeStatusInput, canonicalizeCommandOptionKey, commandOptionFlagLabel, resolveItemTypeRegistry, resolveCommandOptionPolicyState, resolveTypeDefinition, resolveTypeName, validateTypeOptions, acquireLock, printError, buildInvalidTypeError, resolveTypeSynonym, collectRuntimeCreateFieldValues, resolveItemTypesFilePath, resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, EXIT_CODE, ITEM_METADATA_KEY_ORDER, PmCliError, nowIso, resolveIsoOrRelative, getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveCommandHandler, runActiveBeforeMutationHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, applyRegisteredItemFieldDefaultsAndValidation, parseRegisteredItemFieldAssignments, listAllItemMetadataLight, locateItem, createMutationGuardSdk, getHistoryPath, getItemPath, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
-import { requireTerminalReason } from "../lifecycle-policy.js";
+import { requireTerminalReasonWithRecovery } from "../lifecycle-policy.js";
 import { evaluateSimilarityGovernance, similarityAdvisoryWarnings, } from "../similarity.js";
 import { acquireItemMetadataDerivedIndexLock, refreshItemMetadataDerivedIndex, } from "../item-metadata-index.js";
 import { collectNewOrderingCycleWarnings } from "../graph/mutation-advisory.js";
@@ -1384,13 +1384,28 @@ function resolveCreateOrder(unsetKeys, resolvedOptions) {
     return order;
 }
 /** Resolve an author-controlled reason for an item created directly in the close status. */
-function resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution) {
-    if (status !== statusRegistry.close_status ||
-        !settings.governance.require_close_reason) {
-        return { closeReason: undefined, warnings: [] };
+function resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution, nowValue) {
+    if (resolvedOptions.completedAt !== undefined &&
+        status !== statusRegistry.close_status) {
+        throw new PmCliError("--completed-at requires a terminal create status.", EXIT_CODE.USAGE);
     }
+    const completedAt = status !== statusRegistry.close_status
+        ? undefined
+        : resolvedOptions.completedAt === undefined
+            ? nowValue
+            : resolveIsoOrRelative(resolvedOptions.completedAt, new Date(nowValue), "completed-at");
+    if (status !== statusRegistry.close_status) {
+        return { closeReason: undefined, completedAt, warnings: [] };
+    }
+    const reasonInput = settings.governance.require_close_reason
+        ? {
+            explicit: resolvedOptions.closeReason ?? resolvedOptions.message,
+            resolution,
+        }
+        : { explicit: resolvedOptions.closeReason };
     return {
-        closeReason: requireTerminalReason({ explicit: resolvedOptions.message, resolution }, true).closeReason,
+        closeReason: requireTerminalReasonWithRecovery(reasonInput, settings.governance.require_close_reason, { operation: "create", status }).closeReason,
+        completedAt,
         warnings: [],
     };
 }
@@ -1671,9 +1686,10 @@ export async function runCreate(options, global) {
     // GH-249: creating an item directly in the close status must honor
     // governance.require_close_reason, just like `pm close` (errors when missing)
     // and `pm update --status closed` (defaults + warns).
-    const closeReasonResolution = resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution);
+    const closeReasonResolution = resolveCreateCloseReason(status, statusRegistry, settings, resolvedOptions, resolution, nowValue);
     const closeReason = closeReasonResolution.closeReason;
     const closedAt = status === statusRegistry.close_status ? nowValue : undefined;
+    const completedAt = closeReasonResolution.completedAt;
     validationWarnings.push(...closeReasonResolution.warnings);
     const itemMetadata = normalizeItemMetadata({
         id,
@@ -1683,7 +1699,7 @@ export async function runCreate(options, global) {
         type_options: validatedTypeOptions.normalized,
         status,
         closed_at: closedAt,
-        completed_at: closedAt,
+        completed_at: completedAt,
         close_reason: closeReason,
         priority,
         tags,
@@ -1825,4 +1841,4 @@ export const _testOnlyCreateCommand = {
     typeOptionExampleValue,
 };
 //# sourceMappingURL=create.js.map
-//# debugId=5f01dc2b-6239-5724-aa36-8f81b580b76a
+//# debugId=93dc76a3-f205-5a44-85bd-5a6fad80c8d4

package/dist/sdk/lifecycle-policy.d.ts

@@ -58,6 +58,13 @@ export interface TerminalReasonResolution {
     /** Field that supplied the resolved reason. */
     source: TerminalReasonSource;
 }
+/** Presentation context used to make terminal-policy recovery actionable. */
+export interface TerminalReasonRecoveryContext {
+    /** Operation whose input failed terminal-reason governance. */
+    operation: "close" | "create";
+    /** Terminal status requested by a create operation. */
+    status?: string;
+}
 /** Result of applying ordering-edge lifecycle policy to mutable item metadata. */
 export interface TerminalOrderingMutation {
     /** Metadata fields changed by the policy. */
@@ -71,6 +78,8 @@ export declare const DEFAULT_TERMINAL_TRANSITION_POLICY: Readonly<TerminalTransi
 export declare function resolveTerminalReason(input: TerminalReasonInput): TerminalReasonResolution;
 /** Enforce close-reason governance without inventing immutable history content. */
 export declare function requireTerminalReason(input: TerminalReasonInput, required: boolean): TerminalReasonResolution;
+/** Enforce close-reason governance with recovery for a specific operation. */
+export declare function requireTerminalReasonWithRecovery(input: TerminalReasonInput, required: boolean, recovery: TerminalReasonRecoveryContext): TerminalReasonResolution;
 /**
  * Apply terminal ordering policy while clearing only transient blocked-state
  * scalars. Preserving `blocked_by` dependency rows keeps predecessor history