@unbrained/pm-cli 2026.8.18 → 2026.8.20

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

@@ -0,0 +1,134 @@
+/**
+ * @module sdk/agent/refusal-closure
+ *
+ * Scores whether a structured refusal contains enough executable context for
+ * an agent to recover without another discovery round trip.
+ */
+
+!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]="0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778")}catch(e){}}();
+import { EXIT_CODE } from "../../core/shared/constants.js";
+/** Compare a refusal with its optional SDK-owned exact contract. */
+function listContractObservationFindings(observation) {
+    return [
+        observation.expected_error_code !== undefined &&
+            observation.error_code !== observation.expected_error_code
+            ? {
+                code: "error_code_mismatch",
+                probe_id: observation.probe_id,
+                detail: `Expected error code ${observation.expected_error_code}, received ${observation.error_code ?? "<missing>"}.`,
+            }
+            : undefined,
+        observation.expected_allowed_values !== undefined &&
+            JSON.stringify([...observation.allowed_values].sort()) !==
+                JSON.stringify([...observation.expected_allowed_values].sort())
+            ? {
+                code: "incomplete_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal's accepted domain differs from the SDK-owned domain contract.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) === 0
+            ? {
+                code: "missing_suggested_retry_args",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted shell-free suggested retry arguments.",
+            }
+            : undefined,
+        observation.expected_suggested_retry_args !== undefined &&
+            (observation.suggested_retry_args?.length ?? 0) > 0 &&
+            JSON.stringify(observation.suggested_retry_args) !==
+                JSON.stringify(observation.expected_suggested_retry_args)
+            ? {
+                code: "suggested_retry_args_mismatch",
+                probe_id: observation.probe_id,
+                detail: "The refusal's suggested retry arguments differ from the SDK-owned contract.",
+            }
+            : undefined,
+    ];
+}
+/** Return every closure defect contributed by one unique observation. */
+function listObservationFindings(observation) {
+    return [
+        observation.exit_code !== EXIT_CODE.USAGE
+            ? {
+                code: "non_refusal_exit",
+                probe_id: observation.probe_id,
+                detail: `${observation.entrypoint} returned exit code ${observation.exit_code}; a structured usage refusal must return ${EXIT_CODE.USAGE}.`,
+            }
+            : undefined,
+        observation.allowed_values_required !== false &&
+            observation.allowed_values.length === 0
+            ? {
+                code: "missing_allowed_values",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted its complete accepted value domain.",
+            }
+            : undefined,
+        observation.allowed_values.includes(observation.rejected_value)
+            ? {
+                code: "accepted_rejected_value",
+                probe_id: observation.probe_id,
+                detail: `${observation.rejected_value} is both rejected and advertised as allowed.`,
+            }
+            : undefined,
+        observation.suggested_retry.trim().length === 0
+            ? {
+                code: "missing_suggested_retry",
+                probe_id: observation.probe_id,
+                detail: "The refusal omitted an executable suggested retry.",
+            }
+            : undefined,
+        !observation.retry_succeeded
+            ? {
+                code: "retry_failed",
+                probe_id: observation.probe_id,
+                detail: "The advertised suggested retry did not succeed.",
+            }
+            : undefined,
+        ...listContractObservationFindings(observation),
+    ];
+}
+/** Score structured closed-domain refusals and executable retries. */
+export function scorePmRefusalClosure(observations) {
+    const findings = [];
+    const seen = new Set();
+    let closedProbeCount = 0;
+    if (observations.length === 0) {
+        findings.push({
+            code: "empty_corpus",
+            probe_id: "corpus",
+            detail: "At least one real refusal observation is required.",
+        });
+    }
+    for (const observation of observations) {
+        if (seen.has(observation.probe_id)) {
+            findings.push({
+                code: "duplicate_probe",
+                probe_id: observation.probe_id,
+                detail: `${observation.probe_id} was supplied more than once.`,
+            });
+            continue;
+        }
+        seen.add(observation.probe_id);
+        const findingCount = findings.length;
+        for (const finding of listObservationFindings(observation)) {
+            if (finding !== undefined)
+                findings.push(finding);
+        }
+        if (findings.length === findingCount)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id !== right.probe_id
+        ? left.probe_id.localeCompare(right.probe_id)
+        : left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: seen.size,
+        closed_probe_count: closedProbeCount,
+        closure_fraction: seen.size === 0 ? 0 : closedProbeCount / seen.size,
+        findings,
+    };
+}
+//# sourceMappingURL=refusal-closure.js.map
+//# debugId=0ec8c375-e58e-5ce4-b0aa-8a8a4dfa0778

package/dist/sdk/agent/refusal-reachability.d.ts

@@ -37,7 +37,7 @@ export type PmRecoveryReferenceKind = (typeof PM_RECOVERY_REFERENCE_KINDS)[numbe
 /** Behavioral promise attached to a recovery reference. */
 export type PmRecoveryReferenceSemantics = "recovery" | "replacement" | "behavior_preserving";
 /** Literal envelope fields recognized as recovery-reference producers. */
-export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "candidate_command" | "example" | "next_step" | "retry_command")[];
+export declare const PM_RECOVERY_REFERENCE_FIELDS: readonly ("restore_with" | "migration_hint" | "migration_hints" | "suggested_retry" | "next_best_command" | "fallback_candidates" | "examples" | "next_steps" | "suggested_next_steps" | "candidate_commands" | "example" | "candidate_command" | "next_step" | "retry_command")[];
 /** One source file supplied to the producer-census analyzer. */
 export interface PmRecoveryProducerSource {
     /** Repository-relative source path. */
@@ -139,6 +139,28 @@ export interface PmRecoveryReferenceReport {
     /** Stable, sorted conformance findings. */
     findings: PmRecoveryReferenceFinding[];
 }
+/** Per-kind runtime evidence; counts do not claim one observation per source location. */
+export interface PmRecoveryProducerRuntimeCoverage {
+    /** Typed recovery-reference kind. */
+    kind: PmRecoveryReferenceKind;
+    /** Literal source producers discovered for the kind. */
+    source_producers: number;
+    /** Distinct runtime values observed for the kind. */
+    runtime_values: number;
+}
+/** Unified per-kind source-census and runtime-value coverage receipt. */
+export interface PmRecoveryProducerRuntimeReport {
+    /** Whether every source-declared kind emitted at least one runtime value. */
+    ok: boolean;
+    /** Source producer denominator. */
+    source_producer_count: number;
+    /** Distinct runtime-value denominator. */
+    runtime_value_count: number;
+    /** Stable per-kind source and runtime coverage. */
+    coverage_by_kind: PmRecoveryProducerRuntimeCoverage[];
+    /** Kinds with source producers but no runtime evidence. */
+    missing_runtime_kinds: PmRecoveryReferenceKind[];
+}
 /** Census syntax-parsed structured-envelope producers without executing source code. */
 export declare function censusPmRecoveryReferenceProducers(sources: readonly PmRecoveryProducerSource[]): PmRecoveryProducerCensusReport;
 /** Derive typed obligations from every recognized recovery field in an emitted envelope. */
@@ -147,3 +169,7 @@ export declare function derivePmRecoveryReferenceObligations(probeId: string, en
 export declare function verifyPmRefusalReachability(catalog: readonly PmErrorCodeContract[], observations: readonly PmRefusalProbeObservation[]): PmRefusalReachabilityReport;
 /** Verify executable and declared-path proof for emitted recovery references. */
 export declare function verifyPmRecoveryReferences(obligations: readonly PmRecoveryReferenceObligation[], observations: readonly PmRecoveryReferenceObservation[]): PmRecoveryReferenceReport;
+/** Join source-census counts to distinct emitted runtime values by typed kind. */
+export declare function verifyPmRecoveryProducerRuntimeCoverage(census: PmRecoveryProducerCensusReport, obligations: readonly PmRecoveryReferenceObligation[]): PmRecoveryProducerRuntimeReport;
+/** Honest kind-level name for the compatibility implementation above. */
+export declare const verifyPmRecoveryKindRuntimeCoverage: typeof verifyPmRecoveryProducerRuntimeCoverage;

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

@@ -5,7 +5,7 @@
  * generated public error-code catalog.
  */
 
-!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]="7b488d32-9f92-5a80-965e-e2555cd49315")}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]="4f4e7daa-14aa-5dad-8a30-79a4d76159d4")}catch(e){}}();
 import * as nodeModule from "node:module";
 /** Recovery-reference kinds emitted by structured refusal envelopes. */
 export const PM_RECOVERY_REFERENCE_KINDS = [
@@ -566,5 +566,29 @@ export function verifyPmRecoveryReferences(obligations, observations) {
         findings,
     };
 }
+/** Join source-census counts to distinct emitted runtime values by typed kind. */
+export function verifyPmRecoveryProducerRuntimeCoverage(census, obligations) {
+    const runtimeValuesByKind = new Map(PM_RECOVERY_REFERENCE_KINDS.map((kind) => [kind, new Set()]));
+    for (const obligation of obligations) {
+        runtimeValuesByKind.get(obligation.kind).add(obligation.value);
+    }
+    const coverageByKind = PM_RECOVERY_REFERENCE_KINDS.map((kind) => ({
+        kind,
+        source_producers: census.producer_count_by_kind[kind],
+        runtime_values: runtimeValuesByKind.get(kind).size,
+    }));
+    const missingRuntimeKinds = coverageByKind
+        .filter(({ source_producers: sourceProducers, runtime_values: runtimeValues }) => sourceProducers > 0 && runtimeValues === 0)
+        .map(({ kind }) => kind);
+    return {
+        ok: census.ok && missingRuntimeKinds.length === 0,
+        source_producer_count: census.producer_count,
+        runtime_value_count: coverageByKind.reduce((total, { runtime_values: runtimeValues }) => total + runtimeValues, 0),
+        coverage_by_kind: coverageByKind,
+        missing_runtime_kinds: missingRuntimeKinds,
+    };
+}
+/** Honest kind-level name for the compatibility implementation above. */
+export const verifyPmRecoveryKindRuntimeCoverage = verifyPmRecoveryProducerRuntimeCoverage;
 //# sourceMappingURL=refusal-reachability.js.map
-//# debugId=7b488d32-9f92-5a80-965e-e2555cd49315
+//# debugId=4f4e7daa-14aa-5dad-8a30-79a4d76159d4

package/dist/sdk/agent-capability-contracts.d.ts

@@ -1,5 +1,7 @@
 /** Visibility tiers shared by CLI help, completions, docs, extensions, and MCP. */
 export type PmCommandVisibilityTier = "core" | "standard" | "full" | "internal";
+/** Stable capability families shared by every agent-facing command surface. */
+export type PmCommandCapabilityFamily = "workspace" | "intake" | "context" | "lifecycle" | "evidence" | "graph" | "quality" | "automation" | "extensions" | "internal";
 /** One command's canonical agent-surface visibility declaration. */
 export interface PmCommandVisibilityContract {
     /** Canonical command path. */
@@ -7,6 +9,13 @@ export interface PmCommandVisibilityContract {
     /** Minimum surface tier that advertises the command. */
     tier: PmCommandVisibilityTier;
 }
+/** Complete command capability contract with visibility and family ownership. */
+export interface PmCommandCapabilityContract extends PmCommandVisibilityContract {
+    /** Exactly one stable capability family used to group the command. */
+    family: PmCommandCapabilityFamily;
+}
+/** Resolve one command's stable capability family. */
+export declare function resolvePmCommandCapabilityFamily(command: string): PmCommandCapabilityFamily;
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -14,11 +23,15 @@ export interface PmCommandVisibilityContract {
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
+export declare const PM_COMMAND_CAPABILITY_CONTRACTS: readonly PmCommandCapabilityContract[];
+/** Backward-compatible tier-only projection of the capability contract. */
 export declare const PM_COMMAND_VISIBILITY_CONTRACTS: readonly PmCommandVisibilityContract[];
 /** Resolve one command's declared tier; extension commands default to standard. */
 export declare function resolvePmCommandVisibilityTier(command: string, extensionTier?: PmCommandVisibilityTier): PmCommandVisibilityTier;
 /** Return commands visible at a requested tier, preserving contract order. */
 export declare function listPmCommandsForTier(tier: Exclude<PmCommandVisibilityTier, "internal">): string[];
+/** Return commands in one capability family, preserving contract order. */
+export declare function listPmCommandsForFamily(family: PmCommandCapabilityFamily): string[];
 /** MCP profile names accepted by the server and embedding hosts. */
 export type PmMcpToolProfile = "core" | "standard" | "full" | "custom";
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */

package/dist/sdk/agent-capability-contracts.js

@@ -5,7 +5,7 @@
  * surfaces from one public SDK contract.
  */
 
-!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]="6fc2cd04-2fe4-5a0e-944d-fab0f86509e2")}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]="5e77c121-35a2-57d1-9a3e-f33447535c03")}catch(e){}}();
 import { PM_CORE_COMMAND_NAMES } from "./cli-contracts/enum-contracts.js";
 const CORE_COMMANDS = new Set([
     "claim",
@@ -46,6 +46,87 @@ const STANDARD_COMMANDS = new Set([
     "schema",
     "test",
 ]);
+const COMMANDS_BY_FAMILY = Object.freeze({
+    workspace: new Set([
+        "config",
+        "gc",
+        "health",
+        "init",
+        "merge",
+        "profile",
+        "schema",
+        "telemetry",
+        "workspace",
+    ]),
+    intake: new Set(["copy", "create", "focus", "item", "restore"]),
+    context: new Set([
+        "activity",
+        "aggregate",
+        "context",
+        "ctx",
+        "duplicates",
+        "eval",
+        "get",
+        "help",
+        "list",
+        "list-all",
+        "list-blocked",
+        "list-canceled",
+        "list-closed",
+        "list-draft",
+        "list-in-progress",
+        "list-open",
+        "next",
+        "search",
+        "stats",
+    ]),
+    lifecycle: new Set([
+        "claim",
+        "close",
+        "close-many",
+        "close-task",
+        "delete",
+        "pause-task",
+        "item-reopen",
+        "release",
+        "start-task",
+        "update",
+        "update-many",
+    ]),
+    evidence: new Set([
+        "append",
+        "comments",
+        "docs",
+        "events",
+        "files",
+        "history",
+        "history-author-acknowledge",
+        "history-compact",
+        "history-redact",
+        "history-repair",
+        "learnings",
+        "notes",
+    ]),
+    graph: new Set(["deps", "graph", "plan"]),
+    quality: new Set(["assurance", "contracts", "test", "test-all", "validate"]),
+    automation: new Set(["event", "meet", "remind"]),
+});
+const EXTENSION_COMMANDS = new Set([
+    "extension",
+    "install",
+    "package",
+    "packages",
+    "upgrade",
+]);
+/** Resolve one command's stable capability family. */
+export function resolvePmCommandCapabilityFamily(command) {
+    const normalized = command.trim().toLowerCase();
+    for (const [family, commands] of Object.entries(COMMANDS_BY_FAMILY)) {
+        if (commands.has(normalized))
+            return family;
+    }
+    return EXTENSION_COMMANDS.has(normalized) ? "extensions" : "internal";
+}
 /**
  * Canonical visibility contract for every built-in command.
  *
@@ -53,32 +134,39 @@ const STANDARD_COMMANDS = new Set([
  * surface. Internal worker/helper paths are appended below and never advertised
  * by normal help or completion projections.
  */
-export const PM_COMMAND_VISIBILITY_CONTRACTS = Object.freeze([
-    ...PM_CORE_COMMAND_NAMES.map((command) => ({
+export const PM_COMMAND_CAPABILITY_CONTRACTS = Object.freeze([
+    ...PM_CORE_COMMAND_NAMES.flatMap((command) => command === "item" ? ["item-reopen"] : [command]).map((command) => ({
         command,
         tier: CORE_COMMANDS.has(command)
             ? "core"
             : STANDARD_COMMANDS.has(command)
                 ? "standard"
                 : "full",
+        family: resolvePmCommandCapabilityFamily(command),
     })),
     {
         command: "completion-statuses",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-tags",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "completion-types",
         tier: "internal",
+        family: "internal",
     },
     {
         command: "test-runs-worker",
         tier: "internal",
+        family: "internal",
     },
 ]);
+/** Backward-compatible tier-only projection of the capability contract. */
+export const PM_COMMAND_VISIBILITY_CONTRACTS = PM_COMMAND_CAPABILITY_CONTRACTS;
 const TIER_ORDER = {
     core: 0,
     standard: 1,
@@ -88,13 +176,17 @@ const TIER_ORDER = {
 const COMMAND_TIER_BY_NAME = new Map(PM_COMMAND_VISIBILITY_CONTRACTS.map(({ command, tier }) => [command, tier]));
 /** Resolve one command's declared tier; extension commands default to standard. */
 export function resolvePmCommandVisibilityTier(command, extensionTier = "standard") {
-    return COMMAND_TIER_BY_NAME.get(command.trim().toLowerCase()) ?? extensionTier;
+    return (COMMAND_TIER_BY_NAME.get(command.trim().toLowerCase()) ?? extensionTier);
 }
 /** Return commands visible at a requested tier, preserving contract order. */
 export function listPmCommandsForTier(tier) {
     const maximum = TIER_ORDER[tier];
     return PM_COMMAND_VISIBILITY_CONTRACTS.filter((entry) => entry.tier !== "internal" && TIER_ORDER[entry.tier] <= maximum).map((entry) => entry.command);
 }
+/** Return commands in one capability family, preserving contract order. */
+export function listPmCommandsForFamily(family) {
+    return PM_COMMAND_CAPABILITY_CONTRACTS.filter((entry) => entry.family === family).map((entry) => entry.command);
+}
 /** Mapping from one narrow MCP tool to the command contract that tiers it. */
 export const PM_MCP_TOOL_COMMAND_CONTRACTS = Object.freeze({
     pm_append: "append",
@@ -217,17 +309,17 @@ export const PM_MCP_PROMPT_CONTRACTS = Object.freeze([
 ]);
 /** Render the generated command visibility reference used by docs drift gates. */
 export function renderPmCommandVisibilityMarkdown() {
-    const rows = PM_COMMAND_VISIBILITY_CONTRACTS.map(({ command, tier }) => `| \`${command}\` | ${tier} |`);
+    const rows = PM_COMMAND_CAPABILITY_CONTRACTS.map(({ command, tier, family }) => `| \`${command}\` | ${tier} | ${family} |`);
     return [
         "# Generated agent command surface",
         "",
-        "This file is generated from `PM_COMMAND_VISIBILITY_CONTRACTS`. Do not edit it manually.",
+        "This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it manually.",
         "",
-        "| Command | Minimum visibility tier |",
-        "| --- | --- |",
+        "| Command | Minimum visibility tier | Capability family |",
+        "| --- | --- | --- |",
         ...rows,
         "",
     ].join("\n");
 }
 //# sourceMappingURL=agent-capability-contracts.js.map
-//# debugId=6fc2cd04-2fe4-5a0e-944d-fab0f86509e2
+//# debugId=5e77c121-35a2-57d1-9a3e-f33447535c03

package/dist/sdk/cli-contracts/command-aliases.js

@@ -10,7 +10,7 @@
  * are intentionally absent from default help and completion discovery.
  */
 
-!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]="cde15ba9-270e-5e05-baba-7dafbe1bd5da")}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]="9afc5057-afcd-5d6c-a4c1-c2883640fc50")}catch(e){}}();
 export const PM_COMMAND_ALIAS_CONTRACTS = [
     ...[
         ["fetch", "get"],
@@ -29,6 +29,22 @@ export const PM_COMMAND_ALIAS_CONTRACTS = [
         registration: "bootstrap",
         owner: "pm-pbyu",
     })),
+    ...[
+        ["extension list", "extension catalog"],
+        ["extension scaffold", "extension init"],
+        ["package list", "package catalog"],
+        ["package scaffold", "package init"],
+        ["packages list", "packages catalog"],
+        ["packages scaffold", "packages init"],
+    ].map(([alias, canonical]) => ({
+        alias,
+        canonical,
+        canonical_argv: canonical.split(" "),
+        lifecycle: "permanent",
+        hidden: false,
+        registration: "commander",
+        owner: "pm-ya7x55",
+    })),
     {
         alias: "list-all",
         canonical: "list",
@@ -67,4 +83,4 @@ export function renderPmCommandAliasMigrationHint(contract) {
     return `Deprecated command \`${contract.alias}\`; use \`pm ${contract.canonical_argv.join(" ")}\`.`;
 }
 //# sourceMappingURL=command-aliases.js.map
-//# debugId=cde15ba9-270e-5e05-baba-7dafbe1bd5da
+//# debugId=9afc5057-afcd-5d6c-a4c1-c2883640fc50

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]="f7e87e15-b5f3-53ab-86e2-768e94d5d329")}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]="93ce68bd-3140-5361-a6d0-bc60c7304a29")}catch(e){}}();
 export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     {
         target: "title",
@@ -501,17 +501,29 @@ export const CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Seed linked file entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Seed linked test entry (CSV/markdown pairs or - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -989,17 +1001,29 @@ export const UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS = [
     },
     {
         target: "file",
-        keys: ["file"],
+        keys: ["file", "linkedFile"],
         option: "--file <value>",
         description: "Append linked file path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-file <value>",
+                description: "Alias for --file (cross-surface name)",
+            },
+        ],
     },
     {
         target: "test",
-        keys: ["test"],
+        keys: ["test", "linkedTest"],
         option: "--test <value>",
         description: "Append linked test command=<value>,path=<value>,scope=<project|global>,timeout_seconds=<n>,pm_context_mode=<schema|tracker|auto> (also accepts markdown pairs and - for stdin; repeatable)",
         repeatable: true,
+        aliasOptions: [
+            {
+                option: "--linked-test <value>",
+                description: "Alias for --test (cross-surface name)",
+            },
+        ],
     },
     {
         target: "doc",
@@ -1055,4 +1079,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=f7e87e15-b5f3-53ab-86e2-768e94d5d329
+//# debugId=93ce68bd-3140-5361-a6d0-bc60c7304a29

package/dist/sdk/cli-contracts/commander-types.js

@@ -1,6 +1,6 @@
 /** Public contract for list commander string option contracts, shared by SDK and presentation-layer consumers. */
 
-!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]="3b9b9ebe-8d98-5983-8257-b7b77c7e6194")}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]="5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8")}catch(e){}}();
 export const LIST_COMMANDER_STRING_OPTION_CONTRACTS = [
     { target: "status", keys: ["status"] },
     { target: "type", keys: ["type"] },
@@ -147,13 +147,14 @@ export function readFirstValueFromCommanderOptions(options, contract) {
 }
 /** Implements read string array from commander options for the public runtime surface of this module. */
 export function readStringArrayFromCommanderOptions(options, contract) {
+    const values = [];
     for (const key of contract.keys) {
         const candidate = options[key];
         if (Array.isArray(candidate)) {
-            return candidate;
+            values.push(...candidate.filter((value) => typeof value === "string"));
         }
     }
-    return undefined;
+    return values.length > 0 ? values : undefined;
 }
 //# sourceMappingURL=commander-types.js.map
-//# debugId=3b9b9ebe-8d98-5983-8257-b7b77c7e6194
+//# debugId=5f56c4ef-58e1-5cf6-a10e-dfa29b9ad3e8

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

@@ -7,7 +7,7 @@
  * a hand-picked test list.
  */
 
-!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]="8b227cb2-a30d-5384-b9c2-558603181c67")}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]="f4e5eed5-94c2-536a-8685-e20b735de480")}catch(e){}}();
 import { PM_TOOL_ACTIONS } from "./enum-contracts.js";
 import { resolveSubcommandFlagContractsForCommand, } from "./flag-contracts.js";
 import { pmToolActionParameterKeys } from "./tool-schema.js";
@@ -63,6 +63,8 @@ const CLI_CONFIG_SHORTHAND_FLAGS = new Set([
 ]);
 const SDK_TRANSPORT_PARAMETERS = new Set([
     "action",
+    "fullChangedFields",
+    "idOnly",
     "path",
     "pmExecutable",
     "timeoutMs",
@@ -87,6 +89,7 @@ const ACTION_POSITIONAL_PARAMETERS = {
     event: { title: "<title>" },
     files: { lookupPath: "lookup <path...>" },
     meet: { title: "<title>" },
+    "item-reopen": { id: "<id>", reason: "<reason>" },
     merge: { subcommand: "<subcommand>" },
     remind: { title: "<title>" },
     workspace: {
@@ -188,6 +191,9 @@ function actionCommand(action) {
     if (action.startsWith("package-")) {
         return `package ${action.slice("package-".length)}`;
     }
+    if (action.startsWith("item-")) {
+        return `item ${action.slice("item-".length)}`;
+    }
     return action;
 }
 function parameterForFlag(action, flag) {
@@ -384,4 +390,4 @@ export function analyzeSdkCliParameterCompleteness(source = {}) {
     });
 }
 //# sourceMappingURL=completeness.js.map
-//# debugId=8b227cb2-a30d-5384-b9c2-558603181c67
+//# debugId=f4e5eed5-94c2-536a-8685-e20b735de480

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

@@ -30,17 +30,19 @@ export declare const GRAPH_SUBCOMMAND_VALUES: readonly ["ancestors", "descendant
 export type GraphSubcommand = (typeof GRAPH_SUBCOMMAND_VALUES)[number];
 /** Nested lifecycle verbs flattened by SDK and MCP package actions. */
 export declare const PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS: readonly ["init", "install", "uninstall", "explore", "manage", "describe", "reload", "doctor", "catalog", "adopt", "adopt-all", "activate", "deactivate"];
+/** Noun-first item lifecycle verbs flattened for SDK and MCP dispatch. */
+export declare const PM_ITEM_ACTION_SUBCOMMANDS: readonly ["reopen"];
 /** CLI-only presentation commands intentionally omitted from programmatic actions. */
 export declare const PM_CLI_ONLY_TOOL_ACTION_WAIVERS: {
     readonly help: "Commander help rendering has no SDK operation result.";
-    readonly item: "The item namespace only groups lifecycle subcommands already exposed as actions.";
     readonly packages: "The plural package alias only renders package-oriented help.";
 };
 type PmCoreCommandName = (typeof PM_CORE_COMMAND_NAMES)[number];
 type PmCliOnlyToolAction = keyof typeof PM_CLI_ONLY_TOOL_ACTION_WAIVERS;
 type PmExtensionPackageAction = `${"extension" | "package"}-${(typeof PM_EXTENSION_PACKAGE_ACTION_SUBCOMMANDS)[number]}`;
+type PmItemAction = `item-${(typeof PM_ITEM_ACTION_SUBCOMMANDS)[number]}`;
 /** Restricts pm tool action values accepted by command, SDK, and storage contracts. */
-export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction> | PmExtensionPackageAction;
+export type PmToolAction = Exclude<PmCoreCommandName, PmCliOnlyToolAction | "item"> | PmExtensionPackageAction | PmItemAction;
 /**
  * Public pm tool actions derived from the CLI vocabulary. Nested extension and
  * package verbs are flattened for transports that expose one action string.