@unbrained/pm-cli 2026.8.9 → 2026.8.11

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/agent/refusal-reachability.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module sdk/agent/refusal-reachability
+ *
+ * Verifies real-entrypoint observations against refusal states declared by the
+ * generated public error-code catalog.
+ */
+import type { PmErrorCodeContract, PmErrorCodeClass } from "../error-code-catalog.js";
+/** One recorded result from driving a real public entrypoint into a refusal. */
+export interface PmRefusalProbeObservation {
+    /** Stable probe identifier from the owning error-code contract. */
+    probe_id: string;
+    /** Public command entrypoint exercised by the probe. */
+    entrypoint: string;
+    /** Machine-readable code observed at the transport boundary. */
+    code: string;
+    /** Semantic exit class observed at the transport boundary. */
+    exit_class: PmErrorCodeClass;
+}
+/** One actionable conformance failure. */
+export interface PmRefusalReachabilityFinding {
+    /** Stable finding kind for automation. */
+    kind: "duplicate_probe" | "missing_probe" | "wrong_entrypoint" | "wrong_error_code" | "wrong_exit_class" | "undeclared_probe";
+    /** Probe whose declaration or observation failed. */
+    probe_id: string;
+    /** Human-readable mismatch summary. */
+    detail: string;
+}
+/** Complete refusal-reachability conformance receipt. */
+export interface PmRefusalReachabilityReport {
+    /** Whether every declaration and observation agreed. */
+    ok: boolean;
+    /** Number of declared probes evaluated. */
+    declared_probe_count: number;
+    /** Number of real-entrypoint observations supplied. */
+    observed_probe_count: number;
+    /** Stable, sorted conformance findings. */
+    findings: PmRefusalReachabilityFinding[];
+}
+/** Compare declared refusal states with real-entrypoint observations. */
+export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;

package/dist/sdk/agent/refusal-reachability.js

@@ -0,0 +1,72 @@
+/** Compare declared refusal states with real-entrypoint observations. */
+
+!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]="55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c")}catch(e){}}();
+export function verifyPmRefusalReachability(catalog, observations) {
+    const declarations = catalog.flatMap((contract) => (contract.owned_states ?? []).map((state) => ({ contract, state })));
+    const findings = [];
+    const observationsByProbe = new Map();
+    for (const observation of observations) {
+        if (observationsByProbe.has(observation.probe_id)) {
+            findings.push({
+                kind: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        observationsByProbe.set(observation.probe_id, observation);
+    }
+    const declaredProbeIds = new Set(declarations.map(({ state }) => state.probe_id));
+    for (const { contract, state } of declarations) {
+        const observation = observationsByProbe.get(state.probe_id);
+        if (!observation) {
+            findings.push({
+                kind: "missing_probe",
+                probe_id: state.probe_id,
+                detail: `No entrypoint observation was recorded for ${contract.code}.`,
+            });
+            continue;
+        }
+        if (observation.code !== contract.code) {
+            findings.push({
+                kind: "wrong_error_code",
+                probe_id: state.probe_id,
+                detail: `Expected ${contract.code}; observed ${observation.code}.`,
+            });
+        }
+        if (observation.exit_class !== state.expected_exit_class) {
+            findings.push({
+                kind: "wrong_exit_class",
+                probe_id: state.probe_id,
+                detail: `Expected ${state.expected_exit_class}; observed ${observation.exit_class}.`,
+            });
+        }
+        if (!state.entrypoints.includes(observation.entrypoint)) {
+            findings.push({
+                kind: "wrong_entrypoint",
+                probe_id: state.probe_id,
+                detail: `Expected one of ${state.entrypoints.join(", ")}; observed ${observation.entrypoint}.`,
+            });
+        }
+    }
+    for (const observation of observations) {
+        if (!declaredProbeIds.has(observation.probe_id)) {
+            findings.push({
+                kind: "undeclared_probe",
+                probe_id: observation.probe_id,
+                detail: `Observation ${observation.probe_id} has no catalog declaration.`,
+            });
+        }
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.kind.localeCompare(right.kind));
+    return {
+        ok: findings.length === 0,
+        declared_probe_count: declarations.length,
+        observed_probe_count: observations.length,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-reachability.js.map
+//# debugId=55318c8e-1fbd-5abd-b18f-f0cc1f81dd5c

package/dist/sdk/agent/subcommand-recovery.d.ts

@@ -0,0 +1,40 @@
+import { PmCliError, type PmCliErrorRecoveryPayload } from "../../core/shared/errors.js";
+/** Catalog-only alias retained for consumers of the former package lifecycle code. */
+export declare const UNKNOWN_SUBCOMMAND_COMPATIBILITY_CODES: readonly [{
+    readonly code: "unknown_lifecycle_action";
+}];
+/** Inputs for constructing a portable unknown-subcommand refusal. */
+export interface UnknownSubcommandErrorOptions {
+    /** Command family path without the rejected token. */
+    command_path: string;
+    /** Rejected positional token. */
+    token: string;
+    /** Complete declared subcommand vocabulary for the family. */
+    allowed: readonly string[];
+    /** Human-readable command family, defaulting to `pm <command_path>`. */
+    display_name?: string;
+    /** Positional token role used in the compatibility message. */
+    token_kind?: "subcommand" | "action" | "path";
+    /** Arguments that follow the rejected token and should survive a retry. */
+    trailing_args?: readonly string[];
+    /** Family-aware retry that takes precedence over edit-distance recovery. */
+    retry_command?: string;
+    /** Compatibility suffix appended after the allowed-value sentence. */
+    message_suffix?: string;
+    /** Additional ranked recovery candidates supplied by the command family. */
+    fallback_candidates?: PmCliErrorRecoveryPayload["fallback_candidates"];
+    /** Transport exit used by non-CLI protocol adapters. */
+    exit_code?: number;
+    /** Additional family-specific examples. */
+    examples?: readonly string[];
+}
+declare function nearestSubcommand(token: string, allowed: readonly string[]): string | undefined;
+declare function renderCommand(tokens: readonly string[]): string;
+/** Build the shared typed refusal used by CLI, SDK, MCP, and packages. */
+export declare function createUnknownSubcommandError(options: UnknownSubcommandErrorOptions): PmCliError;
+/** Test-only access to deterministic nearest-match behavior. */
+export declare const _testOnly: {
+    nearestSubcommand: typeof nearestSubcommand;
+    renderCommand: typeof renderCommand;
+};
+export {};

package/dist/sdk/agent/subcommand-recovery.js

@@ -0,0 +1,84 @@
+/**
+ * @module sdk/agent/subcommand-recovery
+ *
+ * Provides one SDK-owned refusal contract for unknown positional subcommands.
+ */
+
+!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]="a9b23a46-0bba-5174-8793-dfc37016d1fb")}catch(e){}}();
+import { levenshteinDistanceWithinLimit } from "../../core/shared/levenshtein.js";
+import { EXIT_CODE } from "../../core/shared/constants.js";
+import { PmCliError, } from "../../core/shared/errors.js";
+/** Catalog-only alias retained for consumers of the former package lifecycle code. */
+export const UNKNOWN_SUBCOMMAND_COMPATIBILITY_CODES = [
+    { code: "unknown_lifecycle_action" },
+];
+function nearestSubcommand(token, allowed) {
+    const normalized = token.trim().toLowerCase();
+    if (normalized.length === 0)
+        return undefined;
+    const maxDistance = Math.floor(normalized.length / 3);
+    return allowed
+        .map((candidate) => ({
+        candidate,
+        distance: levenshteinDistanceWithinLimit(normalized, candidate.toLowerCase(), maxDistance) ?? Number.POSITIVE_INFINITY,
+    }))
+        .filter(({ distance }) => Number.isFinite(distance))
+        .sort((left, right) => left.distance !== right.distance
+        ? left.distance - right.distance
+        : left.candidate.localeCompare(right.candidate))[0]?.candidate;
+}
+function renderCommand(tokens) {
+    return ["pm", ...tokens]
+        .map((token) => /^[A-Za-z0-9_./:@=-]+$/u.test(token) ? token : JSON.stringify(token))
+        .join(" ");
+}
+/** Build the shared typed refusal used by CLI, SDK, MCP, and packages. */
+export function createUnknownSubcommandError(options) {
+    const commandPath = options.command_path.trim().replaceAll(/\s+/gu, " ");
+    const normalizedToken = options.token.trim();
+    const token = normalizedToken.length === 0 ? "<empty>" : normalizedToken;
+    const allowed = [...new Set(options.allowed.map((value) => value.trim()))]
+        .filter(Boolean)
+        .sort((left, right) => left.localeCompare(right));
+    if (commandPath.length === 0 || token.length === 0 || allowed.length === 0) {
+        throw new TypeError("Unknown-subcommand contracts require a path, token, and allowed set");
+    }
+    const commandTokens = commandPath.split(" ");
+    const trailingArgs = options.trailing_args ?? [];
+    const displayName = options.display_name ?? `pm ${commandPath}`;
+    const tokenKind = options.token_kind ?? "subcommand";
+    const nearest = options.retry_command
+        ? undefined
+        : nearestSubcommand(token, allowed);
+    const attemptedCommand = renderCommand([
+        ...commandTokens,
+        token,
+        ...trailingArgs,
+    ]);
+    const suggestedRetry = options.retry_command ??
+        (nearest
+            ? renderCommand([...commandTokens, nearest, ...trailingArgs])
+            : undefined);
+    return new PmCliError(`Unknown ${displayName} ${tokenKind} "${token}". Allowed: ${allowed.join(", ")}${options.message_suffix ?? ""}`, options.exit_code ?? EXIT_CODE.USAGE, {
+        code: "unknown_subcommand",
+        reason: "unknown_positional_token",
+        examples: [
+            ...(suggestedRetry ? [suggestedRetry] : []),
+            ...(options.examples ?? []),
+            `pm ${commandPath} --help`,
+        ],
+        nextSteps: suggestedRetry
+            ? [`Retry with the suggested command: ${suggestedRetry}`]
+            : ["Choose one value from recovery.allowed_values."],
+        recovery: {
+            attempted_command: attemptedCommand,
+            allowed_values: allowed,
+            suggested_retry: suggestedRetry,
+            fallback_candidates: options.fallback_candidates,
+        },
+    });
+}
+/** Test-only access to deterministic nearest-match behavior. */
+export const _testOnly = { nearestSubcommand, renderCommand };
+//# sourceMappingURL=subcommand-recovery.js.map
+//# debugId=a9b23a46-0bba-5174-8793-dfc37016d1fb

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

@@ -49,13 +49,21 @@ export interface BootstrapHelpRequest {
 }
 /** Implements parse bootstrap help request for the public runtime surface of this module. */
 export declare function parseBootstrapHelpRequest(argv: string[]): BootstrapHelpRequest;
+/**
+ * Index of the command token in argv — the first non-flag token, skipping the
+ * value-consuming/global bootstrap flags. Returns undefined when there is none
+ * (bare invocation, only global flags, or a leading `--`). Single source of truth
+ * for command-position scanning shared by {@link parseBootstrapCommandName} and the
+ * command-alias rewrite so their precedence rules can never drift apart.
+ */
+export declare function findBootstrapCommandTokenIndex(argv: string[]): number | undefined;
 /** Implements parse bootstrap command name for the public runtime surface of this module. */
 export declare function parseBootstrapCommandName(argv: string[]): string | undefined;
 /** Implements apply bootstrap pager policy for the public runtime surface of this module. */
 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]="eac8ed6b-43c4-54fa-820a-220154001a6b")}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",
@@ -191,7 +194,7 @@ export function parseBootstrapHelpRequest(argv) {
  * for command-position scanning shared by {@link parseBootstrapCommandName} and the
  * command-alias rewrite so their precedence rules can never drift apart.
  */
-function findCommandTokenIndex(argv) {
+export function findBootstrapCommandTokenIndex(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index];
         if (token === "--") {
@@ -217,7 +220,7 @@ function findCommandTokenIndex(argv) {
 }
 /** Implements parse bootstrap command name for the public runtime surface of this module. */
 export function parseBootstrapCommandName(argv) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     return index === undefined ? undefined : argv[index].trim().toLowerCase();
 }
 function shouldDisablePagerForInvocation(argv, bootstrapGlobal) {
@@ -276,7 +279,7 @@ const EXTENSION_ACTION_SYNTAX_TOKENS = new Set([
 ]);
 /** Implements normalize legacy extension action syntax for the public runtime surface of this module. */
 export function normalizeLegacyExtensionActionSyntax(argv) {
-    const extensionIndex = findCommandTokenIndex(argv);
+    const extensionIndex = findBootstrapCommandTokenIndex(argv);
     if (extensionIndex === undefined || argv[extensionIndex] !== "extension") {
         return [...argv];
     }
@@ -307,7 +310,7 @@ const CLI_EXECUTABLE_ALIASES = new Set(["pm", "pm-cli"]);
  * `bunx <package> pm-cli init` behave like direct executable invocations.
  */
 function stripLeadingExecutableAlias(argv, trace) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     if (index === undefined) {
         return argv;
     }
@@ -331,7 +334,7 @@ function stripLeadingExecutableAlias(argv, trace) {
  * value-consuming global flag, mirroring {@link parseBootstrapCommandName}.
  */
 function rewriteCommandAlias(argv, trace) {
-    const index = findCommandTokenIndex(argv);
+    const index = findBootstrapCommandTokenIndex(argv);
     if (index === undefined) {
         return argv;
     }
@@ -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=eac8ed6b-43c4-54fa-820a-220154001a6b

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