@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/core/governance/issue-codes.d.ts

@@ -21,6 +21,15 @@ export interface IssueCodeItem {
     parent?: string | null;
     /** The id of the canonical item this one was closed as a duplicate of, when set. A closed-as-duplicate item has already been adjudicated, so it is excluded from collision detection entirely (GH-278) — re-flagging a resolved duplicate is permanent noise that erodes trust in `validate`. */
     duplicate_of?: string | null;
+    /** Optional body evidence used to disambiguate mixed-case prose compounds. */
+    body?: string | null;
+}
+/** Explicit classifier inputs for repository-specific issue-code formats. */
+export interface IssueCodeDetectionOptions {
+    /** Prefixes configured by the repository, compared case-insensitively. */
+    configuredPrefixes?: readonly string[];
+    /** Item body used only for explicit code markers or backtick references. */
+    evidenceText?: string | null;
 }
 /** A logical issue code shared by two or more items. */
 export interface DuplicateIssueCode {
@@ -42,7 +51,7 @@ export interface DuplicateIssueCode {
  * Accepts unknown-ish input defensively (exported helper SDK consumers may call
  * from untyped JS): a non-string or empty title resolves to `null`.
  */
-export declare function extractIssueCode(title: string | null | undefined): string | null;
+export declare function extractIssueCode(title: string | null | undefined, options?: IssueCodeDetectionOptions): string | null;
 /**
  * Find logical issue codes used by 2+ items. Any item whose title begins with a
  * conventional issue code contributes; codes used by a single item are not
@@ -67,4 +76,4 @@ export declare function extractIssueCode(title: string | null | undefined): stri
  * given (id) is used; duplicate ids (should not occur for a valid corpus) are
  * de-duplicated so an item never inflates its own code's count.
  */
-export declare function findDuplicateIssueCodes(items: readonly IssueCodeItem[]): DuplicateIssueCode[];
+export declare function findDuplicateIssueCodes(items: readonly IssueCodeItem[], options?: Omit<IssueCodeDetectionOptions, "evidenceText">): DuplicateIssueCode[];

package/dist/core/governance/issue-codes.js

@@ -22,8 +22,8 @@
  * (digit immediately followed by a letter — no boundary) does not match.
  */
 
-!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]="087bac58-e32d-5cb8-8fda-0e09075c3f35")}catch(e){}}();
-const ISSUE_CODE_PATTERN = /^([A-Z][A-Z0-9]*-\d+)\b/;
+!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]="8a7fbaf1-917f-5067-b9b6-a9f27c80e291")}catch(e){}}();
+const ISSUE_CODE_PATTERN = /^([A-Z][A-Z0-9]*-\d+)\b/iu;
 /**
  * Extract the leading logical issue code from a title, or `null` when the title
  * does not begin with one. The title is trimmed and upper-cased before matching
@@ -33,16 +33,32 @@ const ISSUE_CODE_PATTERN = /^([A-Z][A-Z0-9]*-\d+)\b/;
  * Accepts unknown-ish input defensively (exported helper SDK consumers may call
  * from untyped JS): a non-string or empty title resolves to `null`.
  */
-export function extractIssueCode(title) {
+export function extractIssueCode(title, options = {}) {
     if (typeof title !== "string") {
         return null;
     }
-    const normalized = title.trim().toUpperCase();
-    if (normalized.length === 0) {
+    const trimmed = title.trim();
+    if (trimmed.length === 0) {
         return null;
     }
-    const match = ISSUE_CODE_PATTERN.exec(normalized);
-    return match ? match[1] : null;
+    const match = ISSUE_CODE_PATTERN.exec(trimmed);
+    if (!match)
+        return null;
+    const rawCode = match[1];
+    const normalized = rawCode.toUpperCase();
+    const rawPrefix = rawCode.slice(0, rawCode.lastIndexOf("-"));
+    const configured = new Set((options.configuredPrefixes ?? []).map((prefix) => prefix.trim().replace(/-+$/u, "").toUpperCase()));
+    const remainder = trimmed.slice(rawCode.length);
+    const evidence = options.evidenceText?.toUpperCase() ?? "";
+    const hasExplicitBodyEvidence = evidence.includes(`ISSUE CODE: ${normalized}`) ||
+        evidence.includes(`ISSUE CODE \`${normalized}\``) ||
+        evidence.includes(`\`${normalized}\``) ||
+        evidence.includes(`[${normalized}]`);
+    const structurallyQualified = rawPrefix === rawPrefix.toUpperCase() ||
+        /^\s*(?::|—|–|\])/u.test(remainder) ||
+        configured.has(rawPrefix.toUpperCase()) ||
+        hasExplicitBodyEvidence;
+    return structurallyQualified ? normalized : null;
 }
 /** Test whether a value is a usable (non-empty after trim) item-id reference. */
 function isNonEmptyIdReference(value) {
@@ -72,7 +88,7 @@ function isNonEmptyIdReference(value) {
  * given (id) is used; duplicate ids (should not occur for a valid corpus) are
  * de-duplicated so an item never inflates its own code's count.
  */
-export function findDuplicateIssueCodes(items) {
+export function findDuplicateIssueCodes(items, options = {}) {
     const byCode = new Map();
     for (const item of items) {
         // A non-string title can never carry a code, so skip it before extraction;
@@ -84,7 +100,10 @@ export function findDuplicateIssueCodes(items) {
         if (isNonEmptyIdReference(item.duplicate_of)) {
             continue;
         }
-        const code = extractIssueCode(item.title);
+        const code = extractIssueCode(item.title, {
+            ...options,
+            evidenceText: item.body,
+        });
         if (code === null) {
             continue;
         }
@@ -130,4 +149,4 @@ export function findDuplicateIssueCodes(items) {
     return duplicates.sort((left, right) => left.code.localeCompare(right.code));
 }
 //# sourceMappingURL=issue-codes.js.map
-//# debugId=087bac58-e32d-5cb8-8fda-0e09075c3f35
+//# debugId=8a7fbaf1-917f-5067-b9b6-a9f27c80e291

package/dist/core/item/item-format.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="65a90a42-eecb-57d3-9f78-3a5f1bc3abd3")}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]="051655a4-8ba7-5118-9758-d9ca377fa7e4")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { isDeepStrictEqual } from "node:util";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, PLAN_STEP_STATUS_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
@@ -422,7 +422,7 @@ function sortDependencies(values) {
         return undefined;
     return [...values]
         .map((value) => ({
-        id: value.id.trim().toLowerCase(),
+        id: value.id.trim(),
         kind: value.kind,
         created_at: value.created_at,
         author: value.author?.trim() || undefined,
@@ -1472,4 +1472,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=65a90a42-eecb-57d3-9f78-3a5f1bc3abd3
+//# debugId=051655a4-8ba7-5118-9758-d9ca377fa7e4

package/dist/core/store/item-store.js

@@ -4,7 +4,7 @@
  * Reads and writes tracker storage with format-aware helpers for Item Store.
  */
 
-!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]="f49b5141-f348-5954-a87e-8fd957593113")}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]="bffd3114-3e85-58ae-90c7-eea5069cdb89")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, projectAfterCommandItemSnapshot, recordAfterCommandAffectedItem, runActiveOnReadHooks, runActiveBeforeMutationHooks, runActiveOnWriteHooks, runActiveServiceOverride, } from "../extensions/index.js";
@@ -63,11 +63,18 @@ function resolveItemFormatSearchOrder(preferredFormat) {
 }
 /** Implements locate item for the public runtime surface of this module. */
 export async function locateItem(pmRoot, rawId, idPrefix = "pm-", preferredFormat, typeToFolder = TYPE_TO_FOLDER) {
+    const trimmedRawId = rawId.trim();
+    const exactRawId = trimmedRawId.startsWith("#")
+        ? trimmedRawId.slice(1)
+        : trimmedRawId;
+    if (exactRawId.length === 0) {
+        return null;
+    }
     const normalizedId = normalizeItemId(rawId, idPrefix);
     const rawNormalizedId = normalizeRawItemId(rawId);
-    const candidateIds = normalizedId === rawNormalizedId
-        ? [normalizedId]
-        : [normalizedId, rawNormalizedId];
+    const candidateIds = [
+        ...new Set([exactRawId, normalizedId, rawNormalizedId]),
+    ].filter((candidateId) => candidateId.length > 0);
     const entries = Object.entries(typeToFolder);
     const searchOrder = resolveItemFormatSearchOrder(preferredFormat);
     for (const candidateId of candidateIds) {
@@ -642,4 +649,4 @@ export async function deleteItem(params) {
     }
 }
 //# sourceMappingURL=item-store.js.map
-//# debugId=f49b5141-f348-5954-a87e-8fd957593113
+//# debugId=bffd3114-3e85-58ae-90c7-eea5069cdb89

package/dist/mcp/server.js

@@ -5,7 +5,7 @@
  * Runs the MCP server adapter that exposes pm actions and contracts to external agents.
  */
 
-!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]="2621052e-5b3f-5ab2-b587-036f375ee187")}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]="77067047-62fc-54e8-9047-ad30580d6125")}catch(e){}}();
 import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -22,13 +22,15 @@ import { isRuntimeRecord, markMcpMutationTransportInput, } from "../sdk/runtime-
 import { attachOutputTokenAccounting } from "../sdk/output-token-accounting.js";
 import { createReproducibleProcessRunner, runWithReproducibleProcessEnvironment, } from "../sdk/reproducibility/process.js";
 import { parseAtomicMutationControls, resolveItemMutationDocument, } from "../sdk/structured-mutations.js";
-import { resolveAuthor, resolvePmRoot } from "../sdk/runtime-primitives.js";
+import { resolveAuthor, resolvePmRoot, resolveWorkspaceRoot, } from "../sdk/runtime-primitives.js";
 import { PM_MCP_ERROR_CODES, PM_MCP_META_KEYS, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, attachMcpServerInfo, buildMcpCompleteResult, buildMcpDiscoverResult, hasMcpClientExtension, isMcpRecord, resolveMcpRequestContext, } from "../sdk/mcp/protocol.js";
 import { PmMcpInputRequiredError, buildMcpInputRequiredResult, parseMcpInputResponses, validateMcpJsonSchema, withMcpCachePolicy, } from "../sdk/mcp/interactions.js";
 import { PM_MCP_TASKS_EXTENSION, createMcpTaskStore, } from "../sdk/mcp/tasks.js";
 import { PmMcpSubscriptionRegistry, } from "../sdk/mcp/subscriptions.js";
 import { extractMcpTraceContext, runWithMcpTraceContext, } from "../sdk/mcp/authorization.js";
 import { LegacyMcpAdapter } from "./legacy-adapter.js";
+import { PM_MCP_APP_CONTRACTS, PM_MCP_APP_MIME_TYPE, PM_MCP_APPS_EXTENSION, PM_MCP_APPS_SERVER_CAPABILITY, decoratePmMcpToolsWithApps, findPmMcpAppByUri, hasPmMcpAppsCapability, renderPmMcpAppHtml, } from "../sdk/mcp/apps.js";
+import { PM_MCP_SKILLS_EXTENSION, PM_MCP_SKILLS_SERVER_CAPABILITY, PmMcpSkillRegistry, assertPmMcpSkillsCapability, } from "../sdk/mcp/skills.js";
 function runMcpAction(args) {
     return runAction(markMcpMutationTransportInput(args));
 }
@@ -53,7 +55,11 @@ const PM_MCP_SERVER_CAPABILITIES = {
     prompts: { listChanged: true },
     resources: { listChanged: true, subscribe: true },
     tools: { listChanged: true },
-    extensions: { [PM_MCP_TASKS_EXTENSION]: {} },
+    extensions: {
+        [PM_MCP_TASKS_EXTENSION]: {},
+        [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY,
+        [PM_MCP_SKILLS_EXTENSION]: PM_MCP_SKILLS_SERVER_CAPABILITY,
+    },
 };
 const PM_MCP_SUBSCRIPTIONS = new Map();
 function createMcpSubscriptionRegistry() {
@@ -87,6 +93,11 @@ const PM_MCP_RUN_TASK_ACTIONS = new Set([
     "test-all",
     "validate",
 ]);
+const PM_MCP_SKILL_METHODS = new Set([
+    "skills/list",
+    "skills/get",
+    "resources/directory/read",
+]);
 const PM_MCP_INSTRUCTIONS = "You have access to native pm CLI tools for git-based project management. " +
     "Use pm_next to pick the next actionable item, or pm_context or pm_search before creating new work. " +
     "Prefer narrow tools (pm_next, pm_context, pm_list, pm_get, pm_search, pm_events, pm_create, pm_mutate, pm_copy, pm_focus, pm_update, pm_append, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_graph, pm_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_profile, pm_config, pm_plan) over pm_run when they cover the operation. " +
@@ -524,6 +535,16 @@ async function readWorkspaceResource(uri, params) {
         ],
     };
 }
+async function loadRequestSkillRegistry(params) {
+    const args = requestWorkspaceArgs(params);
+    const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+    const workspaceRoot = resolveWorkspaceRoot(resolvePmRoot(cwd, typeof args.path === "string" ? args.path : undefined));
+    return PmMcpSkillRegistry.load({
+        packageRoot: resolvePmPackageRoot(),
+        workspaceRoot,
+        packageVersion: PM_MCP_SERVER_VERSION,
+    });
+}
 function renderWorkflowPrompt(params) {
     const paramsRecord = asRecordClone(params);
     const name = readRequiredString(paramsRecord, "name");
@@ -705,7 +726,11 @@ async function dispatchMcpTaskMethod(request, requestContext) {
 async function dispatchModernToolMethod(request, requestContext, clientInfo) {
     if (request.method === "tools/list") {
         const surface = await resolveMcpToolSurface(TOOLS, requestWorkspaceArgs(request.params));
-        return buildMcpCompleteResult(withMcpCachePolicy({ tools: deterministicMcpTools(surface.tools) }, PM_MCP_CACHE_POLICIES.tools), PM_MCP_SERVER_INFO);
+        return buildMcpCompleteResult(withMcpCachePolicy({
+            tools: hasCompatiblePmMcpAppsCapability(requestContext)
+                ? decoratePmMcpToolsWithApps(deterministicMcpTools(surface.tools))
+                : deterministicMcpTools(surface.tools),
+        }, PM_MCP_CACHE_POLICIES.tools), PM_MCP_SERVER_INFO);
     }
     if (shouldCreateMcpTask(request.params, requestContext)) {
         return createMcpTaskForToolCall(request.params, requestContext);
@@ -724,16 +749,59 @@ async function dispatchModernToolMethod(request, requestContext, clientInfo) {
         });
     }
 }
-async function dispatchModernResourceMethod(request) {
+async function dispatchModernResourceMethod(request, requestContext) {
     if (request.method === "resources/list") {
-        const resources = [...PM_MCP_RESOURCE_CONTRACTS].sort((left, right) => left.uri.localeCompare(right.uri));
+        const resources = [
+            ...PM_MCP_RESOURCE_CONTRACTS,
+            ...(hasCompatiblePmMcpAppsCapability(requestContext)
+                ? PM_MCP_APP_CONTRACTS.map((contract) => ({
+                    uri: contract.uri,
+                    name: contract.name,
+                    description: contract.description,
+                    mimeType: PM_MCP_APP_MIME_TYPE,
+                    _meta: { ui: contract.resourceMeta },
+                }))
+                : []),
+        ].sort((left, right) => left.uri.localeCompare(right.uri));
         return buildMcpCompleteResult(withMcpCachePolicy({ resources }, PM_MCP_CACHE_POLICIES.resources), PM_MCP_SERVER_INFO);
     }
     if (request.method === "resources/templates/list") {
         return buildMcpCompleteResult(withMcpCachePolicy({ resourceTemplates: [] }, PM_MCP_CACHE_POLICIES.resources), PM_MCP_SERVER_INFO);
     }
     try {
-        const resource = await readWorkspaceResource(readRequiredString(asRecordClone(request.params), "uri"), request.params);
+        const uri = readRequiredString(asRecordClone(request.params), "uri");
+        const app = findPmMcpAppByUri(uri);
+        let resource;
+        if (app) {
+            if (!hasPmMcpAppsCapability(requestContext)) {
+                throw new PmMcpProtocolError("MCP App resource requires negotiated client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, {
+                    requiredCapabilities: {
+                        extensions: {
+                            [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY,
+                        },
+                    },
+                });
+            }
+            resource = {
+                contents: [
+                    {
+                        uri,
+                        mimeType: PM_MCP_APP_MIME_TYPE,
+                        text: renderPmMcpAppHtml(app),
+                        _meta: { ui: app.resourceMeta },
+                    },
+                ],
+            };
+        }
+        else if (uri.startsWith("skill://")) {
+            assertPmMcpSkillsCapability(requestContext);
+            resource = {
+                ...(await loadRequestSkillRegistry(request.params)).read(uri),
+            };
+        }
+        else {
+            resource = await readWorkspaceResource(uri, request.params);
+        }
         return buildMcpCompleteResult(withMcpCachePolicy(resource, PM_MCP_CACHE_POLICIES.resource), PM_MCP_SERVER_INFO);
     }
     catch (error) {
@@ -744,6 +812,49 @@ async function dispatchModernResourceMethod(request) {
         throw new PmMcpProtocolError(error.message, PM_MCP_ERROR_CODES.invalidParams, { field: "uri" });
     }
 }
+/** Treat an incompatible optional Apps declaration as absent during discovery. */
+function hasCompatiblePmMcpAppsCapability(requestContext) {
+    try {
+        return hasPmMcpAppsCapability(requestContext);
+    }
+    catch (error) {
+        if (error instanceof PmMcpProtocolError)
+            return false;
+        throw error;
+    }
+}
+/** Validate Skills pagination inputs before handing them to the SDK registry. */
+function readSkillPageOptions(params) {
+    if (params.cursor !== undefined && typeof params.cursor !== "string") {
+        throw new PmMcpProtocolError("Skills cursor must be a string", PM_MCP_ERROR_CODES.invalidParams, { field: "cursor" });
+    }
+    if (params.limit !== undefined && typeof params.limit !== "number") {
+        throw new PmMcpProtocolError("Skills limit must be a number", PM_MCP_ERROR_CODES.invalidParams, { field: "limit" });
+    }
+    return {
+        ...(typeof params.cursor === "string" ? { cursor: params.cursor } : {}),
+        ...(typeof params.limit === "number" ? { limit: params.limit } : {}),
+    };
+}
+async function dispatchModernSkillMethod(request, requestContext) {
+    const directoryRead = request.method === "resources/directory/read";
+    assertPmMcpSkillsCapability(requestContext, directoryRead);
+    const params = asRecordClone(request.params);
+    const registry = await loadRequestSkillRegistry(request.params);
+    let result;
+    if (request.method === "skills/list") {
+        result = { ...registry.list(readSkillPageOptions(params)) };
+    }
+    else if (request.method === "skills/get") {
+        result = { skill: registry.get(readRequiredString(params, "uri")) };
+    }
+    else {
+        result = {
+            ...registry.readDirectory(readRequiredString(params, "uri"), readSkillPageOptions(params)),
+        };
+    }
+    return buildMcpCompleteResult(withMcpCachePolicy(result, PM_MCP_CACHE_POLICIES.resource), PM_MCP_SERVER_INFO);
+}
 function dispatchModernPromptMethod(request) {
     const result = request.method === "prompts/list"
         ? withMcpCachePolicy({
@@ -773,6 +884,9 @@ async function dispatchModernMcpRequest(request, meta) {
             removedIn: PM_MCP_PROTOCOL_VERSION,
         });
     }
+    if (PM_MCP_SKILL_METHODS.has(request.method ?? "")) {
+        return dispatchModernSkillMethod(request, requestContext);
+    }
     if (request.method === "tasks/get" ||
         request.method === "tasks/update" ||
         request.method === "tasks/cancel") {
@@ -784,7 +898,7 @@ async function dispatchModernMcpRequest(request, meta) {
     if (request.method === "resources/list" ||
         request.method === "resources/templates/list" ||
         request.method === "resources/read") {
-        return dispatchModernResourceMethod(request);
+        return dispatchModernResourceMethod(request, requestContext);
     }
     if (request.method === "prompts/list" || request.method === "prompts/get") {
         return dispatchModernPromptMethod(request);
@@ -1048,4 +1162,4 @@ if (isInvokedAsMcpMainModule(process.argv[1], import.meta.url)) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=server.js.map
-//# debugId=2621052e-5b3f-5ab2-b587-036f375ee187
+//# debugId=77067047-62fc-54e8-9047-ad30580d6125

package/dist/mcp/tool-definitions.d.ts

@@ -14,6 +14,8 @@ export interface ToolDefinition {
     description: string;
     /** Value that configures or reports input schema for this contract. */
     inputSchema: Record<string, unknown>;
+    /** Optional negotiated extension metadata projected during tools/list. */
+    _meta?: Record<string, unknown>;
 }
 /** MCP transport parameters layered over every canonical action schema. */
 export declare const TOOL_SCHEMA_BASE: {

package/dist/mcp/tool-definitions.js

@@ -4,7 +4,7 @@
  * Defines the Tool Definitions module for pm CLI source.
  */
 
-!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]="90896fb6-ee3e-575d-b103-bbc1a83c6672")}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]="41396cb5-7faf-5642-8746-8d94edb01d86")}catch(e){}}();
 import { GRAPH_SUBCOMMAND_VALUES, PM_DISCOVERABLE_TOOL_ACTIONS, } from "../sdk/cli-contracts/enum-contracts.js";
 import { buildPmActionToolInputSchema } from "../sdk/cli-contracts/tool-schema.js";
 import { RUNTIME_STATUS_ROLE_VALUES } from "../types.js";
@@ -413,7 +413,7 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_comments",
-        description: "List, add, edit, or delete comments on a pm item. Use options.add to append, options.edit=<1-based index> with replacement text to fix a comment, or options.delete=<1-based index> to remove one. " +
+        description: "List, add, edit, or delete comments on a pm item. Use options.add to append, options.edit=<1-based index> with replacement text to fix a comment, or options.delete=<1-based index> to remove one. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. " +
             "List calls default to the most recent 20 comments with total_count/has_more metadata for token efficiency. " +
             "Pass options.limit=N to choose a page size, options.limit=0 for summary-only metadata, or options.full=true for full history.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
@@ -436,14 +436,14 @@ const RAW_TOOLS = [
     },
     {
         name: "pm_notes",
-        description: "List or add structured notes on a pm item. Use options.add to append a note; omit it to list existing notes.",
+        description: "List, add, edit, or delete structured notes on a pm item. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. Omit mutation options to list existing notes.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
             "id",
         ]),
     },
     {
         name: "pm_learnings",
-        description: "List or add learnings on a pm item. Use options.add to capture a learning/insight; omit it to list existing learnings.",
+        description: "List, add, edit, or delete learnings on a pm item. options.ifAbsent applies only to options.add for retry-safe author-and-text deduplication and cannot combine with options.edit or options.delete. Omit mutation options to list existing learnings.",
         inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, [
             "id",
         ]),
@@ -748,4 +748,4 @@ export function buildMcpToolContracts() {
     }).sort((left, right) => left.name.localeCompare(right.name));
 }
 //# sourceMappingURL=tool-definitions.js.map
-//# debugId=90896fb6-ee3e-575d-b103-bbc1a83c6672
+//# debugId=41396cb5-7faf-5642-8746-8d94edb01d86

package/dist/sdk/agent/closed-domain-contracts.d.ts

@@ -15,7 +15,7 @@ export interface PmClosedDomainContract {
     /** Exact argv expected in the refusal's executable recovery. */
     suggested_retry_args: readonly string[];
     /** Stable machine-readable error code that owns the refusal. */
-    error_code: "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
+    error_code: "package_upgrade_modes_mutually_exclusive" | "projection_options_mutually_exclusive" | "unknown_context_intent" | "unknown_field_projection";
     /** Whether a complete accepted-value domain is required in the refusal. */
     allowed_values_required?: boolean;
 }

package/dist/sdk/agent/closed-domain-contracts.js

@@ -6,7 +6,7 @@
  * without changing the stable core corpus.
  */
 
-!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]="35d4f3d7-7ec2-5a8b-bd96-f7e73c658737")}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]="95833d58-d6b9-5ab4-b447-5ce003643fd5")}catch(e){}}();
 import { PM_CONTEXT_INTENT_CONTRACTS } from "../context-intent-contracts.js";
 import { LIST_COMMAND_DEFAULT_PROJECTIONS, listGetProjectionFields, listListProjectionFields, listSearchProjectionFields, } from "../query/projection-contracts.js";
 const REJECTED_INTENT = "not-a-declared-intent";
@@ -107,6 +107,28 @@ export function listCoreClosedDomainContracts() {
             error_code: "projection_options_mutually_exclusive",
             allowed_values_required: false,
         },
+        {
+            probe_id: "package-upgrade-mutually-exclusive-modes",
+            command: "package upgrade",
+            flag: "--cli-only/--packages-only",
+            rejected_value: "--cli-only+--packages-only",
+            refusal_args: [
+                "package",
+                "upgrade",
+                "--cli-only",
+                "--packages-only",
+                "--dry-run",
+            ],
+            allowed_values: [],
+            suggested_retry_args: [
+                "package",
+                "upgrade",
+                "--packages-only",
+                "--dry-run",
+            ],
+            error_code: "package_upgrade_modes_mutually_exclusive",
+            allowed_values_required: false,
+        },
         {
             probe_id: "search-invalid-field",
             command: "search",
@@ -137,4 +159,4 @@ export function renderPmClosedDomainHelp(command, flag) {
     return `Allowed core values: ${canonicalValues.join("|")}.${runtimeSuffix}`;
 }
 //# sourceMappingURL=closed-domain-contracts.js.map
-//# debugId=35d4f3d7-7ec2-5a8b-bd96-f7e73c658737
+//# debugId=95833d58-d6b9-5ab4-b447-5ce003643fd5

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

@@ -6,10 +6,10 @@
  * supplied arguments are preserved byte-for-token.
  */
 
-!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]="4973a995-60f0-5990-9927-371dc6716063")}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]="6084a18e-ccda-57f9-a7d8-45572799c021")}catch(e){}}();
 import { renderPmCommand } from "../command-line.js";
 import { resolveSubcommandFlagContractsForCommand } from "../cli-contracts.js";
-import { parseBootstrapCommandName } from "../cli-bootstrap.js";
+import { parseBootstrapCommandName } from "../cli-contracts/bootstrap-command-scanner.js";
 function normalizeMissingFlag(label) {
     const match = label.trim().match(/--[a-z0-9][a-z0-9_-]*/i);
     return match?.[0]?.replaceAll("_", "-").toLowerCase();
@@ -57,4 +57,4 @@ export function renderMissingOptionRetry(invocationArgv, commandName, missingLab
         : renderPmCommand(retry);
 }
 //# sourceMappingURL=command-recovery.js.map
-//# debugId=4973a995-60f0-5990-9927-371dc6716063
+//# debugId=6084a18e-ccda-57f9-a7d8-45572799c021

package/dist/sdk/agent/task-transcript-contracts.d.ts

@@ -0,0 +1,52 @@
+import { type PmOutputEnvelopeKind } from "../output-contracts.js";
+/** Stable schema version for replayable agent-task transcript corpora. */
+export declare const PM_AGENT_TASK_TRANSCRIPT_VERSION: 2;
+/** Supported strategies for measuring one transcript step's output cost. */
+export declare const PM_AGENT_TASK_ACCOUNTING_MODES: readonly ["self_reported", "independent_transport"];
+/** Token-accounting strategy a replayed transcript step must preserve. */
+export type PmAgentTaskAccountingMode = (typeof PM_AGENT_TASK_ACCOUNTING_MODES)[number];
+/** Scalar value that a replayed transcript must observe at one output path. */
+export type PmAgentTaskExpectedFieldValue = string | number | boolean | null;
+/** Output family expected from one replayed agent-task step. */
+export type PmAgentTaskStepOutputKind = PmOutputEnvelopeKind | "refusal";
+/** Declares one real CLI invocation within a replayable agent task. */
+export interface PmAgentTaskTranscriptStep {
+    /** Stable step identifier unique within its task. */
+    id: string;
+    /** Shell-free CLI arguments, excluding the pm executable, preserved exactly. */
+    args: readonly string[];
+    /** Process status required for the step to satisfy the transcript. */
+    expected_exit_code: number;
+    /** Semantic output family required from the transport. */
+    expected_output_kind: PmAgentTaskStepOutputKind;
+    /** Accounting strategy required from the measured transport. */
+    expected_accounting_mode: PmAgentTaskAccountingMode;
+    /** Dot-separated own-property paths proving required context was consumed. */
+    required_fields: readonly string[];
+    /** Exact terminal scalar values required at selected output paths. */
+    expected_field_values?: Readonly<Record<string, PmAgentTaskExpectedFieldValue>>;
+    /** Stable diagnostic code required from a refusal step. */
+    expected_error_code?: string;
+    /** Exact command or flag required in a refusal identity. */
+    expected_refusal_surface?: string;
+    /** Earlier refusal step whose recovery this successful step executes. */
+    recovery_for?: string;
+}
+/** Versioned multi-step agent workflow suitable for deterministic replay. */
+export interface PmAgentTaskTranscript {
+    /** Stable task identifier used by baselines and reports. */
+    id: string;
+    /** Human-readable task outcome represented by the transcript. */
+    description: string;
+    /** Ordered invocations whose shared workspace state completes the task. */
+    steps: readonly PmAgentTaskTranscriptStep[];
+}
+/** Published collection of replayable agent workflows. */
+export interface PmAgentTaskTranscriptCorpus {
+    /** Schema version governing every transcript in the corpus. */
+    version: typeof PM_AGENT_TASK_TRANSCRIPT_VERSION;
+    /** Complete ordered task set evaluated by the release gate. */
+    tasks: readonly PmAgentTaskTranscript[];
+}
+/** Parse and fail closed on malformed or internally inconsistent transcripts. */
+export declare function parsePmAgentTaskTranscriptCorpus(value: unknown): PmAgentTaskTranscriptCorpus;