@unbrained/pm-cli 2026.8.23 → 2026.8.24

package/dist/sdk/runtime-input.js

@@ -5,12 +5,41 @@
  * primitives are shared by native action dispatchers and MCP-specific adapters.
  */
 
-!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]="0e153ece-4fc0-5134-97f0-c2315aff0031")}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]="2a1e986f-304d-50f6-a405-6afc221bdad5")}catch(e){}}();
 import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { asRecordClone } from "../core/shared/primitives.js";
 import { normalizeListOptions, normalizeUpdateOptions, } from "./cli-contracts/registration-helpers.js";
 import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "./cli-contracts/commander-mutation-options.js";
+import { normalizeBulkIdsValue, } from "../core/io/bulk-ids-input.js";
+import { overlayMutationStdinTokenPolicy, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, } from "../core/item/parse.js";
+const MCP_MUTATION_TRANSPORT = Symbol("pm.mcp-mutation-transport");
+/** Mark an action object decoded from the MCP JSON-RPC transport. */
+export function markMcpMutationTransportInput(input) {
+    Object.defineProperty(input, MCP_MUTATION_TRANSPORT, {
+        value: true,
+        enumerable: true,
+    });
+    return input;
+}
+function isMcpMutationTransportInput(input) {
+    return MCP_MUTATION_TRANSPORT in input;
+}
+function preserveTransportLiteralOptions(source, options) {
+    return isMcpMutationTransportInput(source)
+        ? preserveMutationStdinTokenLiterals(options)
+        : transferMutationStdinTokenPolicy(source, options);
+}
+/** Clone mutation options with overrides while retaining stdin provenance. */
+export function mutationOptionsWithOverrides(source, overrides, omittedKeys = []) {
+    const options = transferMutationStdinTokenPolicy(source, {
+        ...source,
+        ...overrides,
+    });
+    for (const key of omittedKeys)
+        Reflect.deleteProperty(options, key);
+    return options;
+}
 /** Read a non-empty string without altering its caller-provided whitespace. */
 export function readRuntimeString(args, key) {
     const value = args[key];
@@ -119,6 +148,7 @@ const SCALAR_TO_ARRAY_FIELDS = new Set([
     "envClear",
     "env_clear",
 ]);
+const ANNOTATION_SCALAR_TO_ARRAY_FIELDS = new Set([...SCALAR_TO_ARRAY_FIELDS].filter((field) => field !== "file"));
 // Actions where the linked-resource fields `add` and `remove` are string[] arrays.
 // For other actions (comments/notes/learnings) `add` and `remove` are scalar strings
 // and must NOT be auto-promoted.
@@ -129,6 +159,21 @@ const ARRAY_ADD_REMOVE_ACTIONS = new Set([
     "test",
     "test-all",
 ]);
+const SCALAR_ANNOTATION_SOURCE_ACTIONS = new Set([
+    "comments",
+    "notes",
+    "learnings",
+]);
+function assertMcpAnnotationFileUnavailable(action, options) {
+    if (!SCALAR_ANNOTATION_SOURCE_ACTIONS.has(action) ||
+        !Object.prototype.hasOwnProperty.call(options, "file")) {
+        return;
+    }
+    throw new PmCliError(`MCP ${action} does not accept options.file. Pass annotation text in options.add instead.`, EXIT_CODE.USAGE, {
+        code: "mcp_annotation_file_unavailable",
+        required: "Pass annotation text as JSON data; MCP annotation actions cannot read server-local files.",
+    });
+}
 /** Lifecycle actions where a top-level assignee argument aliases the author. */
 const LIFECYCLE_AUTHOR_ALIAS_ACTIONS = new Set([
     "claim",
@@ -171,10 +216,13 @@ const UNIVERSAL_READ_OUTPUT_OPTION_KEYS = [
     "outputCursor",
 ];
 /** Reconcile MCP array/scalar option spellings with CLI flag expectations. */
-export function normalizeMcpOptionsArrays(options, action) {
+export function normalizeMcpOptionsArrays(options, action = "") {
     const result = {};
-    const promoteAddRemove = action !== undefined && ARRAY_ADD_REMOVE_ACTIONS.has(action);
+    const promoteAddRemove = ARRAY_ADD_REMOVE_ACTIONS.has(action);
     const preserveStandaloneNote = action === "files" || action === "files-discover" || action === "docs";
+    const scalarToArrayFields = SCALAR_ANNOTATION_SOURCE_ACTIONS.has(action)
+        ? ANNOTATION_SCALAR_TO_ARRAY_FIELDS
+        : SCALAR_TO_ARRAY_FIELDS;
     for (const [key, value] of Object.entries(options)) {
         if (Array.isArray(value) && ARRAY_TO_CSV_FIELDS.has(key)) {
             result[key] = value.join(",");
@@ -184,7 +232,8 @@ export function normalizeMcpOptionsArrays(options, action) {
             result[key] = value;
             continue;
         }
-        if (typeof value === "string" && SCALAR_TO_ARRAY_FIELDS.has(key)) {
+        if (typeof value === "string" &&
+            scalarToArrayFields.has(key)) {
             result[key] = [value];
             continue;
         }
@@ -198,8 +247,28 @@ export function normalizeMcpOptionsArrays(options, action) {
     }
     return result;
 }
+/** Resolve the explicit or lifecycle-assignee author accepted by MCP actions. */
+function resolveMcpActionAuthor(args, options, action) {
+    const author = readRuntimeString(args, "author");
+    if (author !== undefined) {
+        return author;
+    }
+    return action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action)
+        ? (readRuntimeString(args, "assignee") ??
+            readRuntimeString(options, "assignee"))
+        : undefined;
+}
+/** Add a resolved author only when the normalized options do not provide one. */
+function withResolvedAuthor(options, author) {
+    return author !== undefined && options.author === undefined
+        ? { ...options, author }
+        : options;
+}
 /** Merge hoisted top-level action arguments and author aliases into options. */
 export function optionsWithAuthor(args, action) {
+    const sourceOptions = isRuntimeRecord(args.options)
+        ? args.options
+        : undefined;
     const baseOptions = asRecordClone(args.options);
     const hoistedTopLevel = {};
     const hoistKey = (key) => {
@@ -214,19 +283,14 @@ export function optionsWithAuthor(args, action) {
     for (const key of UNIVERSAL_READ_OUTPUT_OPTION_KEYS) {
         hoistKey(key);
     }
-    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
-    const author = readRuntimeString(args, "author");
-    const authorFromAssignee = action !== undefined && LIFECYCLE_AUTHOR_ALIAS_ACTIONS.has(action)
-        ? (readRuntimeString(args, "assignee") ??
-            readRuntimeString(options, "assignee"))
-        : undefined;
-    if (author && options.author === undefined) {
-        return { ...options, author };
-    }
-    if (authorFromAssignee && options.author === undefined) {
-        return { ...options, author: authorFromAssignee };
+    if (action !== undefined && isMcpMutationTransportInput(args)) {
+        assertMcpAnnotationFileUnavailable(action, baseOptions);
     }
-    return options;
+    const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
+    const stdinPolicySource = isMcpMutationTransportInput(args)
+        ? args
+        : (sourceOptions ?? args);
+    return preserveTransportLiteralOptions(stdinPolicySource, withResolvedAuthor(options, resolveMcpActionAuthor(args, options, action)));
 }
 // GH-170 (pm-pfnx): the narrow pm_files/pm_docs tools spell the CLI --note flag
 // as `addNote` (the shared `note` parameter is the array-typed create/update
@@ -318,10 +382,13 @@ export function extensionOptionsFromArgs(args, options) {
 }
 /** Mutation tools (create/update/close/append/update-many) return a verbose `changed_fields` array. On the agent path we drop it to a `changed_field_count` by default for token efficiency, restoring the full array only when the caller explicitly passes the MCP-level fullChangedFields=true control. Mutation options are forwarded unchanged so runtime fields named `full` remain valid user data. */
 export function withMutationCompaction(args, options) {
+    const runnerOptions = preserveTransportLiteralOptions(options ?? {}, {
+        ...options,
+    });
     return {
         changedFields: args.fullChangedFields === true ? "full" : "compact",
         idOnly: args.idOnly === true,
-        runnerOptions: { ...options },
+        runnerOptions,
     };
 }
 /** Translate flat MCP filter parameters into the shared list-option shape. */
@@ -336,7 +403,7 @@ export function mutationListOptions(options) {
         updatedBefore: readRuntimeScalarString(options, "filterUpdatedBefore"),
         createdAfter: readRuntimeScalarString(options, "filterCreatedAfter"),
         createdBefore: readRuntimeScalarString(options, "filterCreatedBefore"),
-        ids: readRuntimeScalarStringAllowBlank(options, "ids"),
+        ids: normalizeBulkIdsValue(options.ids),
         assignee: readRuntimeScalarString(options, "filterAssignee"),
         assigneeFilter: readRuntimeScalarString(options, "filterAssigneeFilter") ??
             readRuntimeScalarString(options, "filterAssignee_filter"),
@@ -385,12 +452,19 @@ export function graphOptionsFromFlat(options) {
         ...(options.full === true ? { full: true } : {}),
     };
 }
+function normalizeBulkMutationListOptions(options) {
+    const normalized = normalizeListOptions(options);
+    if (options.ids !== undefined) {
+        normalized.ids = normalizeBulkIdsValue(options.ids);
+    }
+    return normalized;
+}
 /** Build close-many command options from one flat MCP parameter payload. */
 export function closeManyOptionsFromFlat(options) {
     return {
         status: readRuntimeString(options, "filterStatus"),
         list: isRuntimeRecord(options.list)
-            ? normalizeListOptions(options.list)
+            ? normalizeBulkMutationListOptions(options.list)
             : mutationListOptions(options),
         reason: readRuntimeString(options, "reason"),
         resolution: readRuntimeString(options, "resolution"),
@@ -474,12 +548,13 @@ export function updateManyOptionsFromFlat(options) {
         const updateSource = isRuntimeRecord(options.update)
             ? options.update
             : updateManyUpdateOptionsFromFlat(options);
+        const normalizedUpdate = preserveTransportLiteralOptions(options, normalizeMcpUpdateOptions(updateSource));
         return {
             status: readRuntimeScalarString(options, "filterStatus"),
             list: isRuntimeRecord(options.list)
-                ? normalizeListOptions(options.list)
+                ? normalizeBulkMutationListOptions(options.list)
                 : mutationListOptions(options),
-            update: normalizeMcpUpdateOptions(updateSource),
+            update: overlayMutationStdinTokenPolicy(updateSource, normalizedUpdate),
             dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
             rollback: readRuntimeString(options, "rollback"),
             checkpoint: options.checkpoint === false ||
@@ -492,7 +567,7 @@ export function updateManyOptionsFromFlat(options) {
     return {
         status: readRuntimeScalarString(options, "filterStatus"),
         list: mutationListOptions(options),
-        update: updateManyUpdateOptionsFromFlat(options),
+        update: preserveTransportLiteralOptions(options, updateManyUpdateOptionsFromFlat(options)),
         dryRun: options.dryRun === true || options.dry_run === true ? true : undefined,
         rollback: readRuntimeString(options, "rollback"),
         checkpoint: options.checkpoint === false ||
@@ -503,4 +578,4 @@ export function updateManyOptionsFromFlat(options) {
     };
 }
 //# sourceMappingURL=runtime-input.js.map
-//# debugId=0e153ece-4fc0-5134-97f0-c2315aff0031
+//# debugId=2a1e986f-304d-50f6-a405-6afc221bdad5

package/dist/sdk/runtime-primitives.d.ts

@@ -14,6 +14,7 @@ export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFie
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, type BulkIdsFileReader, type BulkIdsInputReaders, type BulkIdsStdinReader, type BulkIdsValue, } from "../core/io/bulk-ids-input.js";
 export { type HistoryDiffValueEntry, computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, type HistoryItemHashVersion, } from "../core/history/history.js";
@@ -25,7 +26,7 @@ export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/it
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
 export { toItemRecord } from "../core/item/item-record.js";
 export { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../core/item/parent-reference-policy.js";
-export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, } from "../core/item/parse.js";
+export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, preserveMutationStdinTokenFields, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, shouldResolveMutationStdinTokenField, shouldResolveMutationStdinTokens, splitAcceptanceCriteria, } from "../core/item/parse.js";
 export { resolvePriority } from "../core/item/priority.js";
 export { validateSprintOrReleaseValue } from "../core/item/sprint-release-format.js";
 export { parseStatusFilterCsv } from "../core/item/status-filter.js";

package/dist/sdk/runtime-primitives.js

@@ -7,7 +7,7 @@
  * prefer the typed operations exported by the main SDK barrel.
  */
 
-!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]="472ea74c-138f-584f-b363-e76e100e124c")}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]="be6f7869-f197-5d38-b8d9-faf8f390cd56")}catch(e){}}();
 export { createCheckpointId, loadMutationCheckpoint, restoreCheckpointItems, writeMutationCheckpoint, } from "../core/checkpoint/mutation-checkpoint.js";
 export { flattenFlagListValue, resolveFlagValueKind, } from "../core/extensions/flag-value-types.js";
 export { createUnknownSubcommandError, } from "./agent/subcommand-recovery.js";
@@ -16,6 +16,7 @@ export { applyRegisteredItemFieldDefaultsAndValidation, collectRegisteredItemFie
 export { resolveExtensionRoots } from "../core/extensions/loader.js";
 export { resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, } from "../core/extensions/runtime-registrations.js";
 export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+export { normalizeBulkIdsValue, parseBulkIdsText, resolveCliBulkIdsInput, } from "../core/io/bulk-ids-input.js";
 export { computeHistoryDiff, patchPathToChangedField, } from "../core/history/history-diff.js";
 export { enforceHistoryStreamPolicyForItem, enforceHistoryStreamPolicyForItems, } from "../core/history/history-stream-policy.js";
 export { appendHistoryEntry, CURRENT_HISTORY_ITEM_HASH_VERSION, createHistoryEntry, hashDocument, hashDocumentForVersion, hashEmptyDocument, SUPPORTED_HISTORY_ITEM_HASH_VERSIONS, } from "../core/history/history.js";
@@ -27,7 +28,7 @@ export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/it
 export { canonicalDocument, normalizeItemMetadata, parseItemDocument, serializeItemDocument, } from "../core/item/item-format.js";
 export { toItemRecord } from "../core/item/item-record.js";
 export { assertParentReferenceIsNotSelf, isPlaceholderReferenceToken, normalizeParentReferenceValue, validateMissingParentReference, } from "../core/item/parent-reference-policy.js";
-export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, splitAcceptanceCriteria, } from "../core/item/parse.js";
+export { applyAcceptanceCriteriaMutations, applyTagRemovals, assertNoUnknownCsvKeys, createStdinTokenResolver, looksLikeGenericKeyValueEntry, mergeAdditiveTags, parseCsvKv, parseOptionalNonNegativeInteger, parseOptionalNumber, parseTags, preserveMutationStdinTokenFields, preserveMutationStdinTokenLiterals, transferMutationStdinTokenPolicy, shouldResolveMutationStdinTokenField, shouldResolveMutationStdinTokens, splitAcceptanceCriteria, } from "../core/item/parse.js";
 export { resolvePriority } from "../core/item/priority.js";
 export { validateSprintOrReleaseValue } from "../core/item/sprint-release-format.js";
 export { parseStatusFilterCsv } from "../core/item/status-filter.js";
@@ -81,4 +82,4 @@ export { maybeRunFirstUseTelemetryPrompt } from "../core/telemetry/consent.js";
 export { deriveTelemetryCommandResolution, } from "../core/telemetry/observability.js";
 export { emitTelemetryErrorEvent, finishTelemetryCommand, startTelemetryCommand, } from "../core/telemetry/runtime.js";
 //# sourceMappingURL=runtime-primitives.js.map
-//# debugId=472ea74c-138f-584f-b363-e76e100e124c
+//# debugId=be6f7869-f197-5d38-b8d9-faf8f390cd56

package/dist/sdk/runtime.js

@@ -4,7 +4,7 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="600f391a-c960-5dda-a85a-04d3fa8b1a51")}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]="72111aa2-52b2-53da-a1c8-07ba53a74944")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export * from "./cli-contracts/agent-output-contracts.js";
@@ -72,7 +72,7 @@ import { PROFILE_SUBCOMMANDS, runProfileApply, runProfileLint, runProfileList, r
 import { runHistoryRedact, } from "./history-redact.js";
 import { runMcpHistoryCompactAction, runMcpHistoryRepairAction, } from "./history-mcp.js";
 import { runMcpCloseAction, runMcpReopenAction } from "./lifecycle/mcp-actions.js";
-import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
+import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, graphOptionsFromFlat, mutationListOptions, mutationOptionsWithOverrides, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, parseRuntimeInteger as parseMcpInteger, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeString as readString, readRuntimeStringArray as readStringArray, resolveRuntimeLimit, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction, } from "./runtime-input.js";
 import { runDeps } from "./dependencies.js";
 import { runDocs } from "./docs.js";
 import { runGraph, } from "./graph/run.js";
@@ -252,7 +252,7 @@ export class PmClient {
     append(id, body, options = {}) {
         return this.runTyped("append", {
             id,
-            ...splitFullClientMutationOptions({ ...options, body }),
+            ...splitFullClientMutationOptions(mutationOptionsWithOverrides(options, { body })),
         });
     }
     /** Initialize a workspace with the same semantics as `pm init`. */
@@ -461,7 +461,7 @@ export class PmClient {
             ...(id === undefined ? {} : { id }),
             ...(stepRef === undefined ? {} : { stepRef }),
             ...(reorderTo === undefined ? {} : { reorderTo }),
-            options: { ...options, subcommand },
+            options: mutationOptionsWithOverrides(options, { subcommand }),
         });
     }
     /** Create a durable plan with optional ordered seed steps. */
@@ -1718,22 +1718,13 @@ async function runMcpRestoreAction(ctx) {
         idOnly,
     });
 }
-function withoutLifecycleAssigneeAlias(options) {
-    const updateOptions = { ...options };
-    delete updateOptions.assignee;
-    return updateOptions;
-}
 async function runMcpStartTaskAction(ctx) {
     const pmRoot = resolvePmRoot(process.cwd(), ctx.global.path);
     const settings = await readSettings(pmRoot);
     const inProgressStatus = resolveStartTaskInProgressStatus(resolveRuntimeStatusRegistry(settings.schema));
     const id = requireMcpItemId(ctx);
     const claimResult = await runClaim(id, ctx.force, ctx.global, ctx.options);
-    const updateResult = await runUpdate(id, {
-        ...withoutLifecycleAssigneeAlias(ctx.options),
-        status: inProgressStatus,
-        force: ctx.force,
-    }, ctx.global);
+    const updateResult = await runUpdate(id, mutationOptionsWithOverrides(ctx.options, { status: inProgressStatus, force: ctx.force }, ["assignee"]), ctx.global);
     return { id, action: "start_task", claim: claimResult, update: updateResult };
 }
 async function runMcpPauseTaskAction(ctx) {
@@ -1741,11 +1732,7 @@ async function runMcpPauseTaskAction(ctx) {
     const settings = await readSettings(pmRoot);
     const id = requireMcpItemId(ctx);
     const openStatus = resolveRuntimeStatusRegistry(settings.schema).open_status;
-    const updateResult = await runUpdate(id, {
-        ...withoutLifecycleAssigneeAlias(ctx.options),
-        status: openStatus,
-        force: ctx.force,
-    }, ctx.global);
+    const updateResult = await runUpdate(id, mutationOptionsWithOverrides(ctx.options, { status: openStatus, force: ctx.force }, ["assignee"]), ctx.global);
     const releaseResult = await runRelease(id, ctx.force, ctx.global, ctx.options);
     return {
         id,
@@ -1946,4 +1933,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=600f391a-c960-5dda-a85a-04d3fa8b1a51
+//# debugId=72111aa2-52b2-53da-a1c8-07ba53a74944

package/dist/sdk/scheduling-shortcuts.js

@@ -1,5 +1,6 @@
 
-!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]="32223457-5f57-5049-99cf-c5d766413fb6")}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]="c7c75b13-7317-5089-9869-7e6e22ed95b2")}catch(e){}}();
+import { transferMutationStdinTokenPolicy, } from "./runtime-primitives.js";
 import { runCreate, } from "./lifecycle/create.js";
 const DEFAULT_DURATION = "1h";
 const DEFAULT_START = "now";
@@ -10,7 +11,7 @@ function appendQuotedPair(pairs, key, value) {
     }
 }
 function buildCommonOptions(type, title, options) {
-    return {
+    const createOptions = {
         type,
         title,
         schedulePreset: "lightweight",
@@ -23,6 +24,7 @@ function buildCommonOptions(type, title, options) {
         author: options.author,
         message: options.message,
     };
+    return transferMutationStdinTokenPolicy(options, createOptions);
 }
 async function createMeetingOrEvent(type, title, options, global) {
     const createOptions = buildCommonOptions(type, title, options);
@@ -59,4 +61,4 @@ export function runRemind(title, options, global) {
     return runCreate(createOptions, global);
 }
 //# sourceMappingURL=scheduling-shortcuts.js.map
-//# debugId=32223457-5f57-5049-99cf-c5d766413fb6
+//# debugId=c7c75b13-7317-5089-9869-7e6e22ed95b2

package/dist/sdk/structured-mutations.js

@@ -5,9 +5,10 @@
  * transaction contract and normalizes full item documents for CLI round trips.
  */
 
-!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]="07876c03-63a8-5c69-9c6c-c3446076a382")}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]="3f348972-0c8f-52da-abeb-46690df967d8")}catch(e){}}();
 import crypto from "node:crypto";
 import { normalizeItemId, normalizePrefix } from "../core/item/id.js";
+import { preserveMutationStdinTokenLiterals } from "../core/item/parse.js";
 import { EXIT_CODE, ITEM_PROJECT_CONTEXT_KEYS, } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -244,7 +245,13 @@ export function parseItemMutationBatch(input) {
     if (rows === undefined || rows.length === 0) {
         throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.", EXIT_CODE.USAGE);
     }
-    return rows.map((row, index) => validateMutationRow(row, index));
+    return rows.map((row, index) => {
+        const mutation = validateMutationRow(row, index);
+        if (mutation.options !== undefined) {
+            preserveMutationStdinTokenLiterals(mutation.options);
+        }
+        return mutation;
+    });
 }
 function deriveReferencedItemId(transactionId, reference, idPrefix) {
     const digest = crypto
@@ -571,4 +578,4 @@ export function validateItemMutationRows(value) {
     return parseItemMutationBatch(JSON.stringify(value));
 }
 //# sourceMappingURL=structured-mutations.js.map
-//# debugId=07876c03-63a8-5c69-9c6c-c3446076a382
+//# debugId=3f348972-0c8f-52da-abeb-46690df967d8

package/dist/sdk/workspace-contracts.d.ts

@@ -4,6 +4,7 @@
  * Declares live workspace customization metadata for SDK and MCP consumers.
  */
 import type { RegisteredExtensionCommandDefinition } from "../core/extensions/extension-types.js";
+import type { PmCommandCapabilityFamily } from "./agent-capability-contracts.js";
 import { type RuntimeFieldDefinitionResolved } from "../core/schema/runtime-schema.js";
 import type { RuntimeFieldType } from "../types/index.js";
 /** Runtime custom-field metadata exposed to SDK and MCP consumers. */
@@ -46,6 +47,8 @@ export interface WorkspaceExtensionCommandContract {
     description?: string;
     /** Minimum agent surface tier requested by the extension. */
     tier: "core" | "standard" | "full" | "internal";
+    /** Capability family declared by the extension. */
+    family: PmCommandCapabilityFamily;
 }
 /** Project resolved custom-field definitions into the public workspace shape. */
 export declare function buildWorkspaceFieldContracts(definitions: RuntimeFieldDefinitionResolved[]): WorkspaceFieldContract[];

package/dist/sdk/workspace-contracts.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b9eae1a3-3eb6-5415-86c3-a8e8e1fedd1f")}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]="10052b6f-216f-5b50-81ec-ee373cc13d17")}catch(e){}}();
 import { runtimeFieldOptionTarget, } from "../core/schema/runtime-schema.js";
 /** Project resolved custom-field definitions into the public workspace shape. */
 export function buildWorkspaceFieldContracts(definitions) {
@@ -27,7 +27,8 @@ export function buildWorkspaceExtensionCommandContracts(definitions) {
         })),
         description: definition.description,
         tier: definition.tier ?? "standard",
+        family: definition.family ?? "extensions",
     }));
 }
 //# sourceMappingURL=workspace-contracts.js.map
-//# debugId=b9eae1a3-3eb6-5415-86c3-a8e8e1fedd1f
+//# debugId=10052b6f-216f-5b50-81ec-ee373cc13d17

package/docs/README.md

@@ -50,6 +50,8 @@ pm guide release --json
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
+- [Generated Agent Capability Routing](generated/AGENT_CAPABILITY_ROUTING.md) - contract-derived command families shared by help, guide, skills, completion, MCP, and extensions.
+- [Generated Refusal Closure Census](generated/REFUSAL_CLOSURE_CENSUS.md) - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
 - [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.

package/docs/RELEASING.md

@@ -59,13 +59,13 @@ pnpm version:check
 
 ## One-Time Setup
 
-- Use npm provenance publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs publish signed packages. Keep `id-token: write`, Node 24 or newer, npm 11.5.1 or newer, `NODE_AUTH_TOKEN` from the `release` environment `NPM_TOKEN` secret, and `npm publish --access public --provenance`. The token must authenticate as a maintainer with read-write access to `@unbrained/pm-cli`.
+- Use npm trusted publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs exchange their OIDC identity for a short-lived npm publish credential and publish signed packages. Keep `id-token: write`, the `release` environment, Node 24 or newer, npm 11.5.1 or newer, and `npm publish --access public --provenance`. The npm Trusted Publisher must match repository `unbraind/pm-cli`, workflow `release.yml`, and environment `release`. The release job performs a tokenless `npm publish --dry-run` OIDC exchange before the long release gates and fails early with npm's sanitized exchange diagnostic when the registry refuses the configured identity. Do not pass `registry-url` to `actions/setup-node`: its generated token-placeholder npmrc can suppress npm's OIDC exchange when no token is present. Keep `@unbrained/pm-cli` public; trusted publishing authorizes `npm publish`, not `npm access`, so restore package visibility manually before retrying if an anonymous metadata probe fails. Do not expose `NODE_AUTH_TOKEN` or `NPM_TOKEN` to the publish step; if private dependencies ever require a read token, scope it only to the install step.
 - Add `RELEASE_PAT` to the `release` environment from a maintainer token with `contents:write` and branch-protection bypass rights. Auto Release creates a checked version/changelog commit and tag on `main`; the default `GITHUB_TOKEN` has `contents:write` but cannot satisfy protected-branch required status checks for that freshly-created commit. The workflow does not persist this elevated token during checkout or dependency installation; `run-release-pipeline.mjs` scopes it to the git push process.
 - Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` for the GitHub-hosted Sentry issue-threshold gate; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent, but fails the reliability threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
 - Keep `package.json` repository, homepage, and bugs URLs aligned with `https://github.com/unbraind/pm-cli`.
-- Keep npm publishing compatible with provenance. The release workflow must keep `id-token: write`, a GitHub-hosted runner, Node 24 or newer, npm 11.5.1 or newer, a valid `NPM_TOKEN`, and `npm publish --access public --provenance`.
+- Keep npm publishing compatible with provenance. The release workflow must keep `id-token: write`, a GitHub-hosted runner, Node 24 or newer, npm 11.5.1 or newer, tokenless public metadata probes, and `npm publish --access public --provenance` through the configured Trusted Publisher.
 
 ## Automated Daily Driver
 
@@ -88,6 +88,11 @@ Policy:
 - before dependency installation or build, auto-release verifies that the
   candidate has exact-commit analyzer results or an immutable tree-identical
   reviewed PR head with successful DeepScan and CodeFactor results
+- after the automatic version commit lands, main CI accepts its parent's
+  analyzer evidence only when the commit is the exact immutable-tagged release
+  projection: the canonical commit message, every expected distribution
+  manifest changed by version substitution alone, and only the generated
+  changelog heading changed. Any other path or content still fails closed
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
@@ -248,8 +253,9 @@ protection is enabled and enforced, and CodeFactor plus DeepScan are effective
 required contexts. That summary intentionally cannot attest the admin-only
 strict-update setting: its receipt reports `strict: null`,
 `strict_verified: false`, and `verification_scope: effective_required_checks`
-instead of inventing a positive result. Exact or immutable identical-tree
-analyzer provenance remains mandatory and is emitted beside the policy receipt,
+instead of inventing a positive result. Exact, immutable identical-tree, or
+fully validated deterministic-release analyzer provenance remains mandatory
+and is emitted beside the policy receipt,
 so the restricted-token recovery cannot admit an unanalyzed or different-tree
 candidate. A maintainer token with administration-read access still verifies
 and reports `strict: true` through REST or paginated GraphQL. It reads the
@@ -260,9 +266,23 @@ Squash provenance additionally requires one unambiguous GitHub association to a
 closed PR merged into `main` with the release commit as its merge commit.
 Missing, ambiguous, or different-tree provenance fails closed.
 
+The automatic release commit is the sole non-identical-tree derivation. The
+gate requires one parent, the canonical release subject and body, an immutable
+`v<version>` tag resolving to the candidate, the complete expected manifest
+inventory, exact old-version to new-version substitutions in every manifest,
+and an exact `Unreleased` changelog-heading replacement. It then resolves the
+parent through the same exact or reviewed identical-tree analyzer contract.
+Added, deleted, renamed, missing, or otherwise modified paths are refused, as
+are malformed manifests, changelog edits, untagged commits, and parents without
+successful analyzer evidence. The receipt reports
+`analysis_source: deterministic_release_transform` and names both the release
+parent and the parent's analyzer source; it never describes the changed release
+tree as identical to the analyzed tree.
+
 The supported default-branch arrival path is a reviewed pull request. A direct
 push to `main` is releasable only if both analyzers attached successful evidence
-to that exact commit; when they did not, the gate explicitly refuses the
+to that exact commit or it is the narrowly validated automatic release
+projection above; when neither condition holds, the gate explicitly refuses the
 candidate instead of letting the next scheduled release discover the missing
 precondition after expensive work. CI runs `Release analyzer readiness (main)`
 on every product-relevant push to `main`, providing continuous visibility
@@ -325,7 +345,7 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery. An authenticated exact-version probe keeps already-published access recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
+- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
@@ -351,13 +371,12 @@ git push origin v<version>
   dispatch may do so only when its source-selection preflight pinned the
   checkout to the requested immutable tag; reviewed-main recovery continues
   to refuse publication of a missing target. Only
-  when neither the target nor package metadata is anonymously visible does the
-  same-tag recovery path attempt to restore public package access, because a
-  hidden version can also return 404 to authenticated metadata reads. After a
-  successful access recovery it rechecks anonymous metadata, then either skips
-  the now-visible target or publishes the still-missing version. Permission,
-  authentication, and registry failures stop the workflow instead of risking
-  an immutable-version overwrite. The checked-out tag's `package.json` supplies
+  when neither the target nor package metadata is anonymously visible, the
+  same-tag recovery path fails closed and instructs the maintainer to restore
+  public package visibility outside the workflow. Trusted publishing does not
+  authorize package-access mutations. Permission, authentication, and registry
+  failures stop the workflow instead of risking an immutable-version overwrite.
+  The checked-out tag's `package.json` supplies
   the canonical package identity to both the publish guard and the
   post-publish npm/npx/bunx verifier so those identities cannot drift. The
   explicit stable dist-tag also preserves
@@ -415,8 +434,8 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
   duplicate npm publication for an anonymously visible version. Before
-  installing or running gates, dispatch performs an authenticated exact-version
-  probe. An
+  installing or running gates, dispatch performs an isolated anonymous
+  exact-version probe. An
   existing version keeps the reviewed dispatch-time `main` source and cannot
   be republished. A definitive missing-version response pins the checkout to
   the existing immutable tag, reapplies the version guard, installs the managed
@@ -428,12 +447,12 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.
 - A manual exact-tag `workflow_dispatch` recovery uses isolated anonymous
-  registry probes before any account-level access mutation. A visible package
-  with a missing target version proceeds directly to exact-tag publication, so
-  a publish-capable automation token is not required to change package access.
-  Access recovery is reserved for the ambiguous case where neither the package
-  nor target version is anonymously visible. An already-visible immutable
-  version is still verified and never republished. Recovery starts from the
+  registry probes and never mutates package access. A visible package with a
+  missing target version proceeds directly to exact-tag OIDC publication. When
+  neither the package nor target version is anonymously visible, recovery fails
+  closed until a maintainer restores public visibility outside the workflow. An
+  already-visible immutable version is still verified and never republished.
+  Recovery starts from the
   dispatch-time commit SHA and fails unless the dispatch ref is the repository
   default branch (`main`). It remains on that reviewed source when the exact
   npm version exists. When the version is definitively absent, it switches to