@unbrained/pm-cli 2026.8.9 → 2026.8.10

package/dist/sdk/agent/item-addressing.js

@@ -0,0 +1,208 @@
+/**
+ * @module sdk/item-addressing
+ *
+ * Defines the shared item-address grammar used by CLI adapters. Commands keep
+ * their canonical positional id while accepting `--id` as a compatibility
+ * spelling, so integrations no longer need a per-command addressing table.
+ */
+
+!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]="271cf7c1-f84b-5f59-aa13-ed8cb4ee232f")}catch(e){}}();
+import { resolveSubcommandFlagContractsForCommand, } from "../cli-contracts.js";
+const ITEM_ID_ALIAS_COMMANDS = new Set([
+    "append",
+    "claim",
+    "close",
+    "close-task",
+    "comments",
+    "copy",
+    "delete",
+    "deps",
+    "docs",
+    "files",
+    "focus",
+    "get",
+    "history",
+    "history-compact",
+    "history-redact",
+    "history-repair",
+    "learnings",
+    "notes",
+    "pause-task",
+    "release",
+    "restore",
+    "start-task",
+    "test",
+    "update",
+]);
+const ITEM_ID_ALIAS_SUBCOMMANDS = new Map([
+    ["files", "discover"],
+    ["item", "complete"],
+]);
+const GLOBAL_VALUE_FLAGS = new Set([
+    "--author",
+    "--output-budget",
+    "--output-format",
+    "--output-include",
+    "--output-limit",
+    "--output-session",
+    "--path",
+    "--pm-path",
+]);
+const TRAILING_POSITIONAL_COUNTS = new Map([
+    ["append", 1],
+    ["close", 1],
+    ["close-task", 1],
+    ["comments", 1],
+    ["item complete", 1],
+    ["learnings", 1],
+    ["notes", 1],
+    ["restore", 1],
+]);
+/** Return whether a command participates in the shared item-id alias contract. */
+export function supportsItemIdAlias(commandName) {
+    const normalized = commandName?.trim().toLowerCase() ?? "";
+    return (ITEM_ID_ALIAS_COMMANDS.has(normalized) ||
+        ITEM_ID_ALIAS_SUBCOMMANDS.has(normalized));
+}
+function findCommandIndex(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            return undefined;
+        if (GLOBAL_VALUE_FLAGS.has(token)) {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("-"))
+            continue;
+        return index;
+    }
+    return undefined;
+}
+/** Resolve the positional-id slot for direct and declared nested commands. */
+function resolveItemAddressIndex(argv, commandIndex, commandName) {
+    const declaredSubcommand = ITEM_ID_ALIAS_SUBCOMMANDS.get(commandName);
+    if (declaredSubcommand === undefined)
+        return commandIndex + 1;
+    const usesDeclaredSubcommand = argv[commandIndex + 1]?.toLowerCase() === declaredSubcommand;
+    if (!usesDeclaredSubcommand && !ITEM_ID_ALIAS_COMMANDS.has(commandName)) {
+        return undefined;
+    }
+    return commandIndex + (usesDeclaredSubcommand ? 2 : 1);
+}
+function buildFlagContractMap(commandPath) {
+    const contractsByFlag = new Map();
+    for (const contract of resolveSubcommandFlagContractsForCommand(commandPath)) {
+        for (const flag of [
+            contract.flag,
+            contract.short,
+            ...(contract.aliases ?? []),
+        ]) {
+            if (flag)
+                contractsByFlag.set(flag, contract);
+        }
+    }
+    return contractsByFlag;
+}
+function collectNamedItemIds(argv) {
+    const namedIds = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            break;
+        if (token === "--id") {
+            namedIds.push({ index, consumed: 2, value: argv[index + 1] });
+            index += 1;
+        }
+        else if (token.startsWith("--id=")) {
+            namedIds.push({
+                index,
+                consumed: 1,
+                value: token.slice("--id=".length),
+            });
+        }
+    }
+    return namedIds;
+}
+function consumesSeparateFlagValue(token, nextToken, contractsByFlag) {
+    const separatorIndex = token.indexOf("=");
+    if (separatorIndex >= 0 || nextToken === undefined || nextToken.startsWith("-")) {
+        return false;
+    }
+    const contract = contractsByFlag.get(token);
+    return contract !== undefined && contract.value_type !== "boolean";
+}
+function hasPositionalItemId(argv, addressIndex, commandPath, namedIndex, contractsByFlag) {
+    let trailingPositionals = 0;
+    for (let index = addressIndex; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--")
+            break;
+        if (token === "--id") {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith("--id="))
+            continue;
+        if (!token.startsWith("-")) {
+            if (index < namedIndex)
+                return true;
+            trailingPositionals += 1;
+            continue;
+        }
+        if (consumesSeparateFlagValue(token, argv[index + 1], contractsByFlag)) {
+            index += 1;
+        }
+    }
+    return trailingPositionals > (TRAILING_POSITIONAL_COUNTS.get(commandPath) ?? 0);
+}
+/**
+ * Normalize `pm <command> --id <value>` to the command's positional id form.
+ * The transformation is lossless for every other argument and reports a
+ * conflict instead of guessing when both forms are present.
+ */
+export function normalizeItemAddressInvocation(argv) {
+    const commandIndex = findCommandIndex(argv);
+    const commandName = commandIndex === undefined ? undefined : argv[commandIndex]?.toLowerCase();
+    if (!supportsItemIdAlias(commandName)) {
+        return { argv: [...argv], changed: false, conflict: false };
+    }
+    const commandPath = ITEM_ID_ALIAS_SUBCOMMANDS.get(commandName) ===
+        argv[commandIndex + 1]?.toLowerCase()
+        ? `${commandName} ${argv[commandIndex + 1]?.toLowerCase()}`
+        : commandName;
+    const contractsByFlag = buildFlagContractMap(commandPath);
+    const namedIds = collectNamedItemIds(argv);
+    const named = namedIds[0];
+    if (!named || !named.value?.trim()) {
+        return { argv: [...argv], changed: false, conflict: false };
+    }
+    const addressIndex = resolveItemAddressIndex(argv, commandIndex, commandName);
+    if (addressIndex === undefined) {
+        return { argv: [...argv], changed: false, conflict: false };
+    }
+    if (namedIds.length > 1 ||
+        hasPositionalItemId(argv, addressIndex, commandPath, named.index, contractsByFlag)) {
+        return {
+            argv: [...argv],
+            changed: false,
+            conflict: true,
+            itemId: named.value,
+        };
+    }
+    const withoutNamed = [
+        ...argv.slice(0, named.index),
+        ...argv.slice(named.index + named.consumed),
+    ];
+    const normalizedCommandIndex = findCommandIndex(withoutNamed);
+    const normalizedAddressIndex = resolveItemAddressIndex(withoutNamed, normalizedCommandIndex, commandName);
+    withoutNamed.splice(normalizedAddressIndex, 0, named.value);
+    return {
+        argv: withoutNamed,
+        changed: true,
+        conflict: false,
+        itemId: named.value,
+    };
+}
+//# sourceMappingURL=item-addressing.js.map
+//# debugId=271cf7c1-f84b-5f59-aa13-ed8cb4ee232f

package/dist/sdk/cli-bootstrap.d.ts

@@ -55,7 +55,7 @@ export declare function parseBootstrapCommandName(argv: string[]): string | unde
 export declare function applyBootstrapPagerPolicy(argv: string[]): () => void;
 /** Implements normalize legacy extension action syntax for the public runtime surface of this module. */
 export declare function normalizeLegacyExtensionActionSyntax(argv: string[]): string[];
-type BootstrapNormalizationReason = "executable_alias" | "legacy_extension_action" | "command_alias" | "flag_alias" | "flag_typo" | "bare_key_value" | "list_merge";
+type BootstrapNormalizationReason = "executable_alias" | "legacy_extension_action" | "command_alias" | "item_id_alias" | "flag_alias" | "flag_typo" | "bare_key_value" | "list_merge";
 type BootstrapNormalizationConfidence = "high" | "medium";
 /** Documents the bootstrap normalization event payload exchanged by command, SDK, and package integrations. */
 export interface BootstrapNormalizationEvent {

package/dist/sdk/cli-bootstrap.js

@@ -4,10 +4,13 @@
  * Provides public bootstrap argument normalization for embedded CLI hosts.
  */
 
-!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]="1c2ee12c-9a3e-57bc-8336-f6c558458802")}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]="a53eea26-8b9e-5666-aa32-66b4dc4cd868")}catch(e){}}();
 import { EXECUTABLE_COMMAND_ALIASES, resolveSubcommandFlagContractsForCommand, } from "./cli-contracts.js";
 export { EXECUTABLE_COMMAND_ALIASES };
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
+import { EXIT_CODE } from "../core/shared/constants.js";
+import { PmCliError } from "../core/shared/errors.js";
+import { normalizeItemAddressInvocation } from "./agent/item-addressing.js";
 const GLOBAL_VALUE_CONSUMING_FLAGS = new Set([
     "--pm-path",
     "--path",
@@ -811,10 +814,22 @@ export function normalizeBootstrapInvocation(argv) {
         });
     }
     const aliasNormalized = rewriteCommandAlias(legacyNormalized, trace);
-    const commandName = parseBootstrapCommandName(aliasNormalized);
-    const commandPathName = parseBootstrapCommandPathName(aliasNormalized);
+    const itemAddress = normalizeItemAddressInvocation(aliasNormalized);
+    if (itemAddress.conflict) {
+        throw new PmCliError("Provide the item id either positionally or with --id, not both.", EXIT_CODE.USAGE);
+    }
+    if (itemAddress.changed) {
+        trace.push({
+            from: `--id ${itemAddress.itemId}`,
+            to: [itemAddress.itemId],
+            reason: "item_id_alias",
+            confidence: "high",
+        });
+    }
+    const commandName = parseBootstrapCommandName(itemAddress.argv);
+    const commandPathName = parseBootstrapCommandPathName(itemAddress.argv);
     const lookup = buildFlagLookup(commandPathName ?? commandName);
-    const normalizedArgv = normalizeBootstrapTokens(aliasNormalized, lookup, commandName, trace);
+    const normalizedArgv = normalizeBootstrapTokens(itemAddress.argv, lookup, commandName, trace);
     const linkedTestNormalized = mergeLinkedTestTwoTokenEntries(normalizedArgv, commandName, trace);
     const coalesced = coalesceRepeatedListFlags(linkedTestNormalized, lookup.listCanonicalFlags, GLOBAL_VALUE_CONSUMING_FLAGS, commandName === "create" ? new Set(["--tags"]) : new Set());
     for (const event of coalesced.events) {
@@ -871,4 +886,4 @@ export const _testOnly = {
     resolveCanonicalFlag,
 };
 //# sourceMappingURL=cli-bootstrap.js.map
-//# debugId=1c2ee12c-9a3e-57bc-8336-f6c558458802
+//# debugId=a53eea26-8b9e-5666-aa32-66b4dc4cd868

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

@@ -1,6 +1,6 @@
 /** Creates commander option registration contracts using the validated operation inputs. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b0f52c3d-091d-51db-a4c1-bb177414dd7f")}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]="f7e87e15-b5f3-53ab-86e2-768e94d5d329")}catch(e){}}();
 export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     {
         target: "title",
@@ -242,6 +242,12 @@ export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
         option: "--allow-missing-parent",
         description: "Allow creating with an unresolved parent reference and emit a validation warning",
     },
+    {
+        target: "allowUnresolvedDeps",
+        keys: ["allowUnresolvedDeps", "allow_unresolved_deps"],
+        option: "--allow-unresolved-deps",
+        description: "Allow unresolved local dependency targets and emit explicit warning receipts",
+    },
     {
         target: "reviewer",
         keys: ["reviewer"],
@@ -620,7 +626,7 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
         target: "acceptanceCriteria",
         keys: ["acceptanceCriteria", "acceptance_criteria", "ac"],
         option: "--acceptance-criteria <value>",
-        description: "Set acceptance criteria (repeatable; values join with '; ')",
+        description: "Replace the complete acceptance-criteria list (repeatable values join with '; '); use --remove-ac plus --add-ac for one-entry repair",
         repeatable: true,
         aliasOptions: [
             {
@@ -647,7 +653,7 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
         target: "removeAc",
         keys: ["removeAc", "remove_ac"],
         option: "--remove-ac <value>",
-        description: "Remove one semicolon-free acceptance criterion by exact text match (repeatable)",
+        description: "Remove one semicolon-free acceptance criterion by exact text match; fails if any selector is unmatched (repeatable)",
         repeatable: true,
         aliasOptions: [
             { option: "--remove_ac <value>", description: "Alias for --remove-ac" },
@@ -746,6 +752,12 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
         option: "--allow-missing-parent",
         description: "Allow updating to an unresolved parent reference and emit a validation warning",
     },
+    {
+        target: "allowUnresolvedDeps",
+        keys: ["allowUnresolvedDeps", "allow_unresolved_deps"],
+        option: "--allow-unresolved-deps",
+        description: "Allow unresolved local dependency targets and emit explicit warning receipts",
+    },
     {
         target: "completedAt",
         keys: ["completedAt", "completed_at"],
@@ -1043,4 +1055,4 @@ export const UPDATE_COMMANDER_STRING_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_
 /** Public contract for update commander repeatable option contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS = UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.filter((entry) => entry.repeatable === true).map((entry) => ({ target: entry.target, keys: entry.keys }));
 //# sourceMappingURL=commander-mutation-options.js.map
-//# debugId=b0f52c3d-091d-51db-a4c1-bb177414dd7f
+//# debugId=f7e87e15-b5f3-53ab-86e2-768e94d5d329

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

@@ -7,7 +7,7 @@
  * flag surface stays single-sourced across the CLI, SDK, and MCP boundaries.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="932a6144-c4b4-5153-b8ff-0ef29e308bd0")}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]="e54d77e5-5c63-5ab6-9ea1-71ed8a1e433d")}catch(e){}}();
 import { normalizeUniqueStringList } from "./string-lists.js";
 import { RESERVED_EXTENSION_HOST_FLAGS } from "../../core/extensions/reserved-host-flags.js";
 function normalizeFlagAliasKey(flag) {
@@ -216,6 +216,7 @@ export const AGGREGATE_FLAG_CONTRACTS = [
 ];
 /** Public contract for comments flag contracts, shared by SDK and presentation-layer consumers. */
 export const COMMENTS_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add", aliases: ["--comment", "--body"] },
     { flag: "--stdin" },
     { flag: "--file" },
@@ -234,6 +235,7 @@ function withCursorSemantics(contracts, presentationFlags) {
 }
 /** Public contract for notes flag contracts, shared by SDK and presentation-layer consumers. */
 export const NOTES_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add", aliases: ["--note"] },
     { flag: "--add-json" },
     { flag: "--stdin" },
@@ -251,6 +253,7 @@ export const NOTES_FLAG_CONTRACTS = [
 ];
 /** Public contract for learnings flag contracts, shared by SDK and presentation-layer consumers. */
 export const LEARNINGS_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add", aliases: ["--learning"] },
     { flag: "--limit" },
     { flag: "--full-history" },
@@ -260,6 +263,7 @@ export const LEARNINGS_FLAG_CONTRACTS = [
 ];
 /** Public contract for files flag contracts, shared by SDK and presentation-layer consumers. */
 export const FILES_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add" },
     { flag: "--add-glob" },
     { flag: "--remove" },
@@ -281,6 +285,7 @@ export const FILES_FLAG_CONTRACTS = [
 ];
 /** Public contract for docs flag contracts, shared by SDK and presentation-layer consumers. */
 export const DOCS_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add" },
     { flag: "--add-glob" },
     { flag: "--remove" },
@@ -295,6 +300,7 @@ export const DOCS_FLAG_CONTRACTS = [
 ];
 /** Public contract for history flag contracts, shared by SDK and presentation-layer consumers. */
 export const HISTORY_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--limit" },
     { flag: "--compact" },
     { flag: "--full" },
@@ -319,6 +325,7 @@ export const MERGE_FLAG_CONTRACTS = [
 ];
 /** Public contract for history redact flag contracts, shared by SDK and presentation-layer consumers. */
 export const HISTORY_REDACT_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--literal" },
     { flag: "--regex" },
     { flag: "--replacement" },
@@ -329,6 +336,7 @@ export const HISTORY_REDACT_FLAG_CONTRACTS = [
 ];
 /** Public contract for history repair flag contracts, shared by SDK and presentation-layer consumers. */
 export const HISTORY_REPAIR_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--all" },
     { flag: "--dry-run" },
     { flag: "--author" },
@@ -345,6 +353,7 @@ export const HISTORY_AUTHOR_ACKNOWLEDGE_FLAG_CONTRACTS = [
 ];
 /** Public contract for history compact flag contracts, shared by SDK and presentation-layer consumers. */
 export const HISTORY_COMPACT_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--before" },
     { flag: "--ids", list: true },
     { flag: "--all-over", value_type: "number" },
@@ -693,21 +702,33 @@ export const REINDEX_FLAG_CONTRACTS = [
 ];
 /** Public contract for close flag contracts, shared by SDK and presentation-layer consumers. */
 export const CLOSE_FLAG_CONTRACTS = [
-    { flag: "--reason" },
-    { flag: "--close-reason" },
-    { flag: "--completed-at" },
-    { flag: "--duplicate-of" },
-    { flag: "--author" },
-    { flag: "--message" },
-    { flag: "--validate-close" },
+    { flag: "--id", value_name: "item-id" },
+    { flag: "--reason", value_name: "value" },
+    { flag: "--close-reason", value_name: "value" },
+    { flag: "--completed-at", value_name: "value" },
+    { flag: "--duplicate-of", value_name: "value" },
+    { flag: "--author", value_name: "value" },
+    { flag: "--message", value_name: "value" },
+    {
+        flag: "--validate-close",
+        value_name: "off|warn|strict",
+    },
     // pm-fl0c #11 (2026-05-28) + Codex P2 follow-up: inline closure-validation
     // fields. Surface them through the contract so `pm contracts --command
     // close`, the JSON help payload, and bootstrap flag normalization /
     // suggestions all stay consistent with the commander registration.
-    { flag: "--resolution" },
-    { flag: "--expected-result", aliases: ["--expected_result", "--expected"] },
-    { flag: "--actual-result", aliases: ["--actual_result", "--actual"] },
-    { flag: "--force" },
+    { flag: "--resolution", value_name: "value" },
+    {
+        flag: "--expected-result",
+        aliases: ["--expected_result", "--expected"],
+        value_name: "value",
+    },
+    {
+        flag: "--actual-result",
+        aliases: ["--actual_result", "--actual"],
+        value_name: "value",
+    },
+    { flag: "--force", value_type: "boolean" },
 ];
 // close-many shares update-many's `--filter-*` scoping family and close's
 // inline closure-validation fields. The shared close reason is required for the
@@ -746,6 +767,7 @@ export const CLOSE_MANY_FLAG_CONTRACTS = [
 ];
 /** Public contract for append flag contracts, shared by SDK and presentation-layer consumers. */
 export const APPEND_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--body", short: "-b" },
     { flag: "--author" },
     { flag: "--message" },
@@ -753,6 +775,7 @@ export const APPEND_FLAG_CONTRACTS = [
 ];
 /** Public contract for claim flag contracts, shared by SDK and presentation-layer consumers. */
 export const CLAIM_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author", aliases: ["--assignee"] },
     { flag: "--message" },
     { flag: "--force" },
@@ -772,12 +795,14 @@ export const CLAIM_FLAG_CONTRACTS = [
 ];
 /** Public contract for restore flag contracts, shared by SDK and presentation-layer consumers. */
 export const RESTORE_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author" },
     { flag: "--message" },
     { flag: "--force" },
 ];
 /** Public contract for delete flag contracts, shared by SDK and presentation-layer consumers. */
 export const DELETE_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--dry-run" },
     { flag: "--author" },
     { flag: "--message" },
@@ -785,27 +810,31 @@ export const DELETE_FLAG_CONTRACTS = [
 ];
 /** Public contract for release flag contracts, shared by SDK and presentation-layer consumers. */
 export const RELEASE_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author", aliases: ["--assignee"] },
     { flag: "--message" },
     { flag: "--force" },
 ];
 /** Public contract for start task flag contracts, shared by SDK and presentation-layer consumers. */
 export const START_TASK_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author", aliases: ["--assignee"] },
     { flag: "--message" },
     { flag: "--force" },
 ];
 /** Public contract for pause task flag contracts, shared by SDK and presentation-layer consumers. */
 export const PAUSE_TASK_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author", aliases: ["--assignee"] },
     { flag: "--message" },
     { flag: "--force" },
 ];
 /** Public contract for close task flag contracts, shared by SDK and presentation-layer consumers. */
 export const CLOSE_TASK_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--author", aliases: ["--assignee"] },
     { flag: "--message" },
-    { flag: "--validate-close" },
+    { flag: "--validate-close", value_name: "off|warn|strict" },
     { flag: "--force" },
 ];
 /** Shared create-passthrough flags for every scheduling shortcut (GH-217). */
@@ -839,6 +868,7 @@ export const REMIND_FLAG_CONTRACTS = [
 ];
 /** Public contract for test flag contracts, shared by SDK and presentation-layer consumers. */
 export const TEST_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--add" },
     { flag: "--add-json" },
     { flag: "--remove" },
@@ -977,6 +1007,7 @@ const ITEM_OWNERSHIP_AND_ISSUE_FLAG_CONTRACTS = [
     { flag: "--assignee" },
     { flag: "--parent" },
     { flag: "--allow-missing-parent" },
+    { flag: "--allow-unresolved-deps" },
     { flag: "--reviewer" },
     { flag: "--risk" },
     { flag: "--confidence" },
@@ -1112,6 +1143,7 @@ export const ITEM_MUTATE_FLAG_CONTRACTS = [
 ];
 /** Atomic item-completion flags shared by contracts, help, and completions. */
 export const ITEM_COMPLETE_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--transaction-id", value_name: "value", required: true },
     { flag: "--reason", value_name: "value" },
     { flag: "--file", value_name: "value", repeatable: true },
@@ -1124,7 +1156,7 @@ export const ITEM_COMPLETE_FLAG_CONTRACTS = [
     { flag: "--expected-result", value_name: "value" },
     { flag: "--actual-result", value_name: "value" },
     { flag: "--completed-at", value_name: "value" },
-    { flag: "--validate-close", value_name: "mode" },
+    { flag: "--validate-close", value_name: "off|warn|strict" },
     { flag: "--lock-ttl-seconds", value_name: "n" },
     { flag: "--lock-wait-ms", value_name: "n" },
     { flag: "--dry-run" },
@@ -1133,15 +1165,20 @@ export const ITEM_COMPLETE_FLAG_CONTRACTS = [
 ];
 /** Public contract for copy flag contracts, shared by SDK and presentation-layer consumers. */
 export const COPY_FLAG_CONTRACTS = [
-    { flag: "--title" },
-    { flag: "--author" },
-    { flag: "--message" },
+    { flag: "--id", value_name: "item-id" },
+    { flag: "--title", value_name: "value" },
+    { flag: "--author", value_name: "value" },
+    { flag: "--message", value_name: "value" },
     { flag: "--allow-duplicate", value_type: "boolean" },
 ];
 /** Public contract for focus flag contracts, shared by SDK and presentation-layer consumers. */
-export const FOCUS_FLAG_CONTRACTS = [{ flag: "--clear" }];
+export const FOCUS_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
+    { flag: "--clear" },
+];
 /** Public contract for update flag contracts, shared by SDK and presentation-layer consumers. */
 export const UPDATE_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--stdin-json" },
     { short: "-t", flag: "--title" },
     { short: "-d", flag: "--description" },
@@ -1272,6 +1309,7 @@ export const UPDATE_MANY_FLAG_CONTRACTS = [
     { flag: "--regression" },
     { flag: "--customer-impact" },
     { flag: "--customer_impact" },
+    { flag: "--allow-unresolved-deps" },
     { flag: "--dep" },
     { flag: "--dep-remove" },
     { flag: "--dep_remove" },
@@ -1407,10 +1445,11 @@ export const CONTEXT_FLAG_CONTRACTS = withCursorSemantics([
 ]));
 /** Public contract for get flag contracts, shared by SDK and presentation-layer consumers. */
 export const GET_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--for", value_name: "intent" },
     { flag: "--token-budget", aliases: ["--token_budget"] },
     { flag: "--depth" },
-    { flag: "--full" },
+    { flag: "--full", value_type: "boolean" },
     { flag: "--fields", list: true },
     { flag: "--at" },
     { flag: "--tree" },
@@ -1426,6 +1465,7 @@ export const GUIDE_FLAG_CONTRACTS = [
 ];
 /** Public contract for deps flag contracts, shared by SDK and presentation-layer consumers. */
 export const DEPS_FLAG_CONTRACTS = [
+    { flag: "--id", value_name: "item-id" },
     { flag: "--format" },
     { flag: "--max-depth" },
     { flag: "--collapse" },
@@ -1734,7 +1774,8 @@ export function resolveSubcommandFlagContractsForCommand(commandName) {
         extraParts.length === 0) {
         return withSubcommandGlobalFlags(resolveExtensionLifecycleFlagContracts(rootCommand, lifecycleSubcommand));
     }
-    return withSubcommandGlobalFlags(SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND.get(normalized) ?? []);
+    const contracts = SUBCOMMAND_FLAG_CONTRACTS_BY_COMMAND.get(normalized) ?? [];
+    return withSubcommandGlobalFlags(contracts);
 }
 /** Renders a space-separated, de-duplicated list of every flag spelling (short, canonical, and aliases) for shell-completion candidate generation, optionally appending the shared subcommand-global flags. */
 export function toCompletionFlagString(flagContracts, includeGlobal = true) {
@@ -1755,4 +1796,4 @@ export function toCompletionFlagString(flagContracts, includeGlobal = true) {
     return normalizeUniqueStringList(all).join(" ");
 }
 //# sourceMappingURL=flag-contracts.js.map
-//# debugId=932a6144-c4b4-5153-b8ff-0ef29e308bd0
+//# debugId=e54d77e5-5c63-5ab6-9ea1-71ed8a1e433d

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

@@ -4,7 +4,7 @@
  * Provides CLI runtime support for Registration Helpers.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d44229ca-8c70-5d55-a168-32bfe66711e6")}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]="5f92dd0d-4eb1-5a7b-8891-931dd15deb81")}catch(e){}}();
 import { Option } from "commander";
 import { pathExists, refreshSearchArtifactsForMutation, shouldRunSearchRefreshInForeground, EXIT_CODE, PmCliError, printError, printResult, writeStdout, getSettingsPath, resolvePmRoot, readSettings, runActiveServiceOverride, setActiveCommandResult, } from "../runtime-primitives.js";
 import { ACTIVITY_COMMANDER_STRING_OPTION_CONTRACTS, CONTEXT_COMMANDER_STRING_OPTION_CONTRACTS, CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, CREATE_COMMANDER_STRING_OPTION_CONTRACTS, LIST_COMMANDER_STRING_OPTION_CONTRACTS, NEXT_COMMANDER_STRING_OPTION_CONTRACTS, SEARCH_COMMANDER_STRING_OPTION_CONTRACTS, UPDATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS, UPDATE_COMMANDER_STRING_OPTION_CONTRACTS, readFirstValueFromCommanderOptions, readFirstStringFromCommanderOptions, readStringArrayFromCommanderOptions, } from "../cli-contracts.js";
@@ -320,6 +320,10 @@ export function normalizeCreateOptions(commandOptions, options = {}) {
             "allowMissingParent",
             "allow_missing_parent",
         ]) === true,
+        allowUnresolvedDeps: anyOptionTrue(commandOptions, [
+            "allowUnresolvedDeps",
+            "allow_unresolved_deps",
+        ]) === true,
         allowDuplicate: optionTrue(commandOptions, "allowDuplicate") === true,
         reviewer: readCreateString("reviewer"),
         risk: readCreateString("risk"),
@@ -405,6 +409,10 @@ export function normalizeUpdateOptions(commandOptions) {
         ownershipDependencyBypass: commandOptions.ownershipDependencyBypass === true ? true : undefined,
         assignee: readUpdateString("assignee"),
         parent: readUpdateString("parent"),
+        allowUnresolvedDeps: anyOptionTrue(commandOptions, [
+            "allowUnresolvedDeps",
+            "allow_unresolved_deps",
+        ]) === true,
         reviewer: readUpdateString("reviewer"),
         risk: readUpdateString("risk"),
         confidence: readUpdateString("confidence"),
@@ -970,4 +978,4 @@ export const _testOnly = {
     collectMutationItemIds,
 };
 //# sourceMappingURL=registration-helpers.js.map
-//# debugId=d44229ca-8c70-5d55-a168-32bfe66711e6
+//# debugId=5f92dd0d-4eb1-5a7b-8891-931dd15deb81