@unbrained/pm-cli 2026.8.18 → 2026.8.19

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.18"
+    "version": "2026.8.19"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.18",
+      "version": "2026.8.19",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2026.8.19 - 2026-08-19
+
+### Fixed
+
+- The writer-lease renewal test decides from wall-clock progress instead of the lease record, so correct behaviour is reported as a failure whenever the restore finishes first ([pm-15qgul](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-15qgul.toon))
+- Core command flag_invocations misclassify valueless booleans as required string values ([pm-pcy92t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-pcy92t.toon))
+- A budget-truncated read is resumable on one surface and terminal on five, and the only recovery the envelope names is to abandon the budget that truncated it ([pm-8nev0o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8nev0o.toon))
+- Both token gates are structurally unable to fail: one measures only help payloads, the other measures command output against a three-item fixture, so no check anywhere compares real output to the ceiling the contract declares ([pm-9sui7t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9sui7t.toon))
+- Plan positional-action help is undiscoverable: pm plan create --help is rejected as an unknown command ([pm-2tan](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2tan.toon))
+- MCP update keys and CLI update flags diverge in name (linkedFile/linkedTest vs --file/--test), so an agent that reads the MCP contract and writes a CLI command produces a guaranteed unknown-option refusal ([pm-y0htkd](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y0htkd.toon))
+- Context calibration recovery names a nonexistent package script ([pm-xa3t0o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xa3t0o.toon))
+
+### Other
+
+- Every executable command and positional action publishes a typed, validated argument contract ([pm-ya7x55](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ya7x55.toon))
+
 ## 2026.8.18 - 2026-08-18
 
 ### Added
@@ -88,7 +104,6 @@
 - Make every failing health verdict self-indexing and attach gate severity to findings ([pm-larv4r](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-larv4r.toon))
 - GH-1004: history-repair remains writer-version-specific across 2026.8.7 and 2026.8.13 ([pm-igdvfq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-igdvfq.toon))
 - Assurance gates preserve zero-valued counts and report actionable source failures ([pm-xmmafu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xmmafu.toon))
-- A budget-truncated read is resumable on one surface and terminal on five, and the only recovery the envelope names is to abandon the budget that truncated it ([pm-8nev0o](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8nev0o.toon))
 - Ranking explanation is sized by the workspace rather than by the answer: explaining two returned rows emits one entry per active item and ignores the token budget entirely ([pm-okgxwa](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-okgxwa.toon))
 - The unknown-option refusal asserts the option belongs on another command path without checking, so a spelling that exists nowhere sends the reader on an unbounded search ([pm-in23qu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-in23qu.toon))
 - The gate verdict withholds its evidence as a declaration-order prefix, so the assertion that produced a blocking verdict can be the row the default read drops ([pm-e5gl05](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-e5gl05.toon))
@@ -551,7 +566,6 @@
 - GH-790/GH-791: pm merge install reports workspace_root in a different canonical form depending on which channel resolved it, so the same repository has two non-equal spellings on macOS and Windows ([pm-ihmfs6](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ihmfs6.toon))
 - The dependency token budget is enforced against a different representation than the one emitted, so a command that reports staying inside 16k tokens delivers about 45k ([pm-t2t709](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-t2t709.toon))
 - pm activity has no default bound: a bare invocation returns all 40,446 history entries at 1.59M tokens, 397x the ceiling its own contract declares ([pm-z2j1qt](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-z2j1qt.toon))
-- Both token gates are structurally unable to fail: one measures only help payloads, the other measures command output against a three-item fixture, so no check anywhere compares real output to the ceiling the contract declares ([pm-9sui7t](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-9sui7t.toon))
 - Sentry PM-CLI-2N: malformed missing tags crash normalizeItemMetadata before search can report the item ([pm-89neyq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-89neyq.toon))
 - pm-governance-audit comments-audit limit contract contradicts runtime alias semantics ([pm-v657](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-v657.toon))
 - pm-governance-audit dedupe-audit rejects --status all, breaking explicit all-lifecycle duplicate sweeps ([pm-mp49](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mp49.toon))

package/dist/cli/error-guidance.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="763daf66-1309-50bc-8783-8c232e4d690d")}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]="367d9302-9e1e-5813-a913-e4e87f34d8b9")}catch(e){}}();
 import { resolveRecoveryCommandName } from "../sdk/agent/command-recovery.js";
 import { renderPmCommand } from "./argv-utils.js";
 import { discoverNearbyPmRoot } from "../sdk/tracker-root-discovery.js";
@@ -177,6 +177,7 @@ function normalizeRecoveryPayload(payload) {
         normalized.option_scope = payload.option_scope;
     }
     assignRecoveryString(normalized, "suggested_retry", payload.suggested_retry);
+    assignRecoveryCollection(normalized, "suggested_retry_args", payload.suggested_retry_args);
     if (typeof payload.retry_after_ms === "number" &&
         Number.isSafeInteger(payload.retry_after_ms) &&
         payload.retry_after_ms >= 0) {
@@ -1240,4 +1241,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=763daf66-1309-50bc-8783-8c232e4d690d
+//# debugId=367d9302-9e1e-5813-a913-e4e87f34d8b9

package/dist/cli/help-content.js

@@ -1,9 +1,11 @@
+
+!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]="9cf83881-9464-5c18-b196-ee669057a873")}catch(e){}}();
+import { parseBootstrapHelpRequest } from "./bootstrap-args.js";
+import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
 // Compact help/narrative surfaces show at most the first example. Centralizing this
 // keeps the empty-examples guard in one place for renderCompactHelpBundle and
 // resolveHelpNarrative (both must degrade to an empty list rather than [undefined]).
 /** Implements first example or empty for the public runtime surface of this module. */
-
-!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]="a97a61f2-df10-5c2b-8497-f8de17a6222d")}catch(e){}}();
 export function firstExampleOrEmpty(examples) {
     return examples.length > 0 ? [examples[0]] : [];
 }
@@ -596,9 +598,7 @@ const HELP_BY_COMMAND_PATH = {
     },
     delete: {
         why: "Removes an item while preserving history evidence and lock/ownership checks.",
-        examples: [
-            'pm delete pm-a1b2 --message "Remove duplicate item"',
-        ],
+        examples: ['pm delete pm-a1b2 --message "Remove duplicate item"'],
     },
     append: {
         why: "Adds implementation notes to body without replacing existing content.",
@@ -641,7 +641,7 @@ const HELP_BY_COMMAND_PATH = {
         examples: [
             'pm learnings pm-a1b2 --add "Avoid direct test-runner commands in linked tests; use sandbox runner."',
             'pm learnings pm-a1b2 --add "text: lesson with commas, key-like words, and punctuation-safe context"',
-            'pm learnings pm-a1b2 --edit 1 --file docs/corrected-learning.md',
+            "pm learnings pm-a1b2 --edit 1 --file docs/corrected-learning.md",
             "pm learnings pm-a1b2 --delete 2",
             "pm learnings pm-a1b2 --limit 10",
         ],
@@ -753,15 +753,11 @@ const HELP_BY_COMMAND_PATH = {
     },
     release: {
         why: "Releases an active claim when paused, handed off, or completed.",
-        examples: [
-            'pm release pm-a1b2 --message "Release after closure"',
-        ],
+        examples: ['pm release pm-a1b2 --message "Release after closure"'],
     },
     "start-task": {
         why: "Lifecycle alias that claims an item and sets status to in_progress.",
-        examples: [
-            'pm start-task pm-a1b2 --message "Start implementation"',
-        ],
+        examples: ['pm start-task pm-a1b2 --message "Start implementation"'],
     },
     "pause-task": {
         why: "Lifecycle alias that sets status to open and releases active assignment.",
@@ -884,6 +880,29 @@ export function attachRichHelpText(program, argv = process.argv.slice(2)) {
     for (const [commandPath, bundle] of Object.entries(HELP_BY_COMMAND_PATH)) {
         attachBundleByPath(program, commandPath, bundle, detailMode);
     }
+    const requestedPath = normalizeHelpCommandPath(parseBootstrapHelpRequest(argv).commandPathTokens.join(" "));
+    const positionalAction = resolvePmPositionalActionContract(requestedPath);
+    if (positionalAction) {
+        attachBundleByPath(program, positionalAction.parent, {
+            why: positionalAction.description,
+            examples: [positionalAction.example],
+            tips: [
+                `Action path: pm ${positionalAction.command}`,
+                formatPmPositionalActionFlagTip(positionalAction.accepted_flags),
+            ],
+        }, detailMode);
+        return;
+    }
+    const positionalActions = PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent }) => parent === requestedPath);
+    if (positionalActions.length > 0) {
+        attachBundleByPath(program, requestedPath, {
+            why: `Dispatches one declared positional action: ${positionalActions.map(({ action }) => action).join("|")}.`,
+            examples: positionalActions.map(({ example }) => example),
+            tips: [
+                `Inspect one action directly with pm ${requestedPath} <action> --help --json.`,
+            ],
+        }, detailMode);
+    }
 }
 /** Public contract for test only, shared by SDK and presentation-layer consumers. */
 export const _testOnly = {
@@ -891,4 +910,4 @@ export const _testOnly = {
     renderDetailedHelpBundle,
 };
 //# sourceMappingURL=help-content.js.map
-//# debugId=a97a61f2-df10-5c2b-8497-f8de17a6222d
+//# debugId=9cf83881-9464-5c18-b196-ee669057a873

package/dist/cli/help-json-payload.d.ts

@@ -6,6 +6,8 @@
 import { Command } from "commander";
 import { resolveItemTypeRegistry } from "../sdk/runtime-primitives.js";
 import { type HelpOptionSummary, type ExtensionCommandHelpDescriptor } from "./extension-command-help.js";
+import { type PmPositionalActionContract } from "../sdk/cli-contracts/grammar-contracts.js";
+import { type PmCommandCapabilityFamily, type PmCommandVisibilityTier } from "../sdk/agent-capability-contracts.js";
 /** Documents the help argument summary payload exchanged by command, SDK, and package integrations. */
 export interface HelpArgumentSummary {
     /** Value that configures or reports name for this contract. */
@@ -25,6 +27,10 @@ export interface HelpSubcommandSummary {
     aliases: string[];
     /** Value that configures or reports description for this contract. */
     description: string;
+    /** Shared command visibility tier. */
+    tier: PmCommandVisibilityTier;
+    /** Shared command capability family. */
+    family: PmCommandCapabilityFamily;
 }
 declare function resolveCommandFromPathTokens(root: Command, pathTokens: string[]): Command | null;
 declare function readOptionAttributeName(option: unknown): string | null;
@@ -33,6 +39,14 @@ declare function buildHelpOptionSummaries(command: Command): HelpOptionSummary[]
 declare function compactHelpOptionAliases(options: HelpOptionSummary[]): HelpOptionSummary[];
 declare function buildHelpArgumentSummaries(command: Command): HelpArgumentSummary[];
 declare function buildHelpSubcommandSummaries(command: Command): HelpSubcommandSummary[];
+interface PositionalActionHelpProjection {
+    arguments: HelpArgumentSummary[];
+    options: HelpOptionSummary[];
+    subcommands: HelpSubcommandSummary[];
+    usage: string;
+}
+/** Build the command/action structural view shared by every JSON help field. */
+declare function buildPositionalActionHelpProjection(action: PmPositionalActionContract | undefined, targetCommand: Command, resolvedPath: string, allOptions: HelpOptionSummary[]): PositionalActionHelpProjection;
 declare function buildJsonHelpPayload(rootProgram: Command, targetCommand: Command, argv: string[], requestedPath: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Record<string, unknown>;
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
 export declare function maybeRenderBootstrapJsonHelp(rootProgram: Command, argv: string[], extensionDescriptors: ReadonlyMap<string, ExtensionCommandHelpDescriptor>): Promise<boolean>;
@@ -44,6 +58,7 @@ export declare const _testOnly: {
     attachCreateUpdatePolicyHelpText: typeof attachCreateUpdatePolicyHelpText;
     buildCreateUpdatePolicyHelpText: typeof buildCreateUpdatePolicyHelpText;
     buildJsonHelpPayload: typeof buildJsonHelpPayload;
+    buildPositionalActionHelpProjection: typeof buildPositionalActionHelpProjection;
     buildHelpArgumentSummaries: typeof buildHelpArgumentSummaries;
     buildHelpOptionSummaries: typeof buildHelpOptionSummaries;
     buildHelpSubcommandSummaries: typeof buildHelpSubcommandSummaries;

package/dist/cli/help-json-payload.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="42b9782e-2151-54b0-98ce-8c5ae810c424")}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]="abdb8d3e-8c1b-511e-b25b-220d5a40ae3f")}catch(e){}}();
 import { hasSubcommandFlagContractsForCommand, PM_CORE_COMMAND_NAMES, } from "../sdk/cli-contracts.js";
 import { commandOptionFlagLabel, resolveCommandOptionPolicyState, resolveTypeDefinition, EXIT_CODE, printError, writeStdout, } from "../sdk/runtime-primitives.js";
 import { buildDynamicExtensionHelpOptionSummaries, mergeHelpOptionSummaries, findCommandByPath, findDirectChildCommand, commandAliases, } from "./extension-command-help.js";
@@ -10,6 +10,8 @@ import { extractProvidedOptionFlags, renderPmCommand } from "./argv-utils.js";
 import { formatCommanderErrorForJson } from "./error-guidance.js";
 import { BUILTIN_TYPE_HELP_VALUES, buildUnknownCommandGuidanceFromRuntime, } from "./commander-usage.js";
 import { resolveCreateExplicitEmptyFlag } from "../sdk/agent/create-option-policy.js";
+import { formatPmPositionalActionFlagTip, PM_POSITIONAL_ACTION_CONTRACTS, resolvePmPositionalActionContract, } from "../sdk/cli-contracts/grammar-contracts.js";
+import { resolvePmCommandCapabilityFamily, resolvePmCommandVisibilityTier, } from "../sdk/agent-capability-contracts.js";
 function resolveCommandFromPathTokens(root, pathTokens) {
     if (pathTokens.length === 0) {
         return root;
@@ -20,7 +22,8 @@ function resolveCommandFromPathTokens(root, pathTokens) {
     }
     const requestedPath = pathTokens.join(" ");
     if (!PM_CORE_COMMAND_NAMES.some((commandName) => commandName === requestedPath) &&
-        !hasSubcommandFlagContractsForCommand(requestedPath)) {
+        !hasSubcommandFlagContractsForCommand(requestedPath) &&
+        !resolvePmPositionalActionContract(requestedPath)) {
         return null;
     }
     for (let length = pathTokens.length - 1; length > 0; length -= 1) {
@@ -170,19 +173,29 @@ function buildHelpArgumentSummaries(command) {
             : null;
         return {
             name: rawName.trim(),
-            required: argument.required === true,
+            required: argument.required === true ||
+                description?.toLowerCase().startsWith("required;") === true,
             variadic: argument.variadic === true,
             description,
         };
     });
 }
 function buildHelpSubcommandSummaries(command) {
-    return command.commands
-        .map((entry) => ({
-        name: entry.name().trim(),
-        aliases: commandAliases(entry),
-        description: entry.description().trim(),
-    }))
+    return command
+        .createHelp()
+        .visibleCommands(command)
+        .filter((entry) => entry.name() !== "help" || command.parent === null)
+        .map((entry) => {
+        const rootCommand = normalizeHelpCommandPath(getCommandPath(entry))
+            .split(" ")[0];
+        return {
+            name: entry.name().trim(),
+            aliases: commandAliases(entry),
+            description: entry.description().trim(),
+            tier: resolvePmCommandVisibilityTier(rootCommand),
+            family: resolvePmCommandCapabilityFamily(rootCommand),
+        };
+    })
         .sort((left, right) => left.name.localeCompare(right.name));
 }
 function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor) {
@@ -210,6 +223,57 @@ function buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescript
         detail_mode: detailMode,
     };
 }
+/** Build the command/action structural view shared by every JSON help field. */
+function buildPositionalActionHelpProjection(action, targetCommand, resolvedPath, allOptions) {
+    if (!action) {
+        const argumentsList = buildHelpArgumentSummaries(targetCommand);
+        const registeredSubcommands = buildHelpSubcommandSummaries(targetCommand);
+        const registeredSubcommandNames = new Set(registeredSubcommands.map(({ name }) => name));
+        return {
+            arguments: argumentsList,
+            options: allOptions,
+            subcommands: [
+                ...registeredSubcommands,
+                ...PM_POSITIONAL_ACTION_CONTRACTS.filter(({ parent, action: name }) => parent === resolvedPath && !registeredSubcommandNames.has(name)).map(({ action: name, description }) => ({
+                    name,
+                    aliases: [],
+                    description,
+                    tier: resolvePmCommandVisibilityTier(resolvedPath.split(" ")[0]),
+                    family: resolvePmCommandCapabilityFamily(resolvedPath.split(" ")[0]),
+                })),
+            ].sort((left, right) => left.name.localeCompare(right.name)),
+            usage: [
+                resolvedPath,
+                argumentsList.reduce((usage, argument) => argument.required
+                    ? usage.replace(`[${argument.name}${argument.variadic ? "..." : ""}]`, `<${argument.name}${argument.variadic ? "..." : ""}>`)
+                    : usage, targetCommand.usage()),
+            ]
+                .filter((token) => token.length > 0)
+                .join(" "),
+        };
+    }
+    const acceptedFlags = new Set(action.accepted_flags);
+    return {
+        arguments: action.slots.map(({ name, required, variadic, value_kind: valueKind, polymorphic }) => ({
+            name,
+            required,
+            variadic,
+            description: polymorphic
+                ? `Polymorphic ${valueKind} value; inspect the action contract before mutation.`
+                : `${valueKind.replaceAll("_", " ")} value.`,
+        })),
+        options: allOptions.filter(({ long, aliases }) => (long !== null && acceptedFlags.has(long)) ||
+            aliases.some((alias) => acceptedFlags.has(alias))),
+        subcommands: [],
+        usage: [
+            action.command,
+            ...action.slots.map(({ name, required, variadic }) => {
+                const token = variadic ? `${name}...` : name;
+                return required ? `<${token}>` : `[${token}]`;
+            }),
+        ].join(" "),
+    };
+}
 function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, extensionDescriptors) {
     const detailMode = resolveHelpDetailMode(argv);
     const commanderPath = normalizeHelpCommandPath(getCommandPath(targetCommand));
@@ -217,29 +281,42 @@ function buildJsonHelpPayload(rootProgram, targetCommand, argv, requestedPath, e
     const resolvedPath = requestedCommandPath.length > commanderPath.length
         ? requestedCommandPath
         : commanderPath;
-    const commandPath = resolvedPath.length > 0 ? resolvedPath : undefined;
+    const positionalAction = resolvePmPositionalActionContract(resolvedPath);
+    const projectedPath = positionalAction?.command ?? resolvedPath;
+    const commandPath = projectedPath.length > 0 ? projectedPath : undefined;
+    const rootCommandPath = commandPath?.split(" ")[0];
     const fallbackNarrative = resolveHelpNarrative(commandPath, detailMode);
     const extensionDescriptor = commandPath
         ? extensionDescriptors.get(commandPath)
         : undefined;
     const narrative = buildJsonHelpNarrative(detailMode, fallbackNarrative, extensionDescriptor);
-    const optionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
-    const subcommands = buildHelpSubcommandSummaries(targetCommand);
+    const allOptionSummaries = compactHelpOptionAliases(mergeHelpOptionSummaries(buildHelpOptionSummaries(targetCommand), buildDynamicExtensionHelpOptionSummaries(extensionDescriptor)));
+    const projection = buildPositionalActionHelpProjection(positionalAction, targetCommand, projectedPath, allOptionSummaries);
     return {
         format: "pm_help_v1",
         detail_mode: detailMode,
         root_command: rootProgram.name(),
         requested_path: requestedPath,
-        resolved_path: resolvedPath.length > 0 ? resolvedPath : rootProgram.name(),
-        description: targetCommand.description(),
-        usage: targetCommand.usage(),
-        intent: narrative.intent,
-        examples: narrative.examples,
-        tips: narrative.tips,
-        arguments: buildHelpArgumentSummaries(targetCommand),
-        options: optionSummaries,
-        subcommands,
-        has_subcommands: subcommands.length > 0,
+        resolved_path: projectedPath.length > 0 ? projectedPath : rootProgram.name(),
+        visibility_tier: rootCommandPath === undefined
+            ? null
+            : resolvePmCommandVisibilityTier(rootCommandPath),
+        capability_family: rootCommandPath === undefined
+            ? null
+            : resolvePmCommandCapabilityFamily(rootCommandPath),
+        description: positionalAction?.description ?? targetCommand.description(),
+        usage: projection.usage,
+        intent: positionalAction?.description ?? narrative.intent,
+        examples: positionalAction
+            ? [positionalAction.example]
+            : narrative.examples,
+        tips: positionalAction
+            ? [formatPmPositionalActionFlagTip(positionalAction.accepted_flags)]
+            : narrative.tips,
+        arguments: projection.arguments,
+        options: projection.options,
+        subcommands: projection.subcommands,
+        has_subcommands: projection.subcommands.length > 0,
     };
 }
 /** Implements maybe render bootstrap json help for the public runtime surface of this module. */
@@ -402,6 +479,7 @@ export const _testOnly = {
     attachCreateUpdatePolicyHelpText,
     buildCreateUpdatePolicyHelpText,
     buildJsonHelpPayload,
+    buildPositionalActionHelpProjection,
     buildHelpArgumentSummaries,
     buildHelpOptionSummaries,
     buildHelpSubcommandSummaries,
@@ -411,4 +489,4 @@ export const _testOnly = {
     resolveCommandFromPathTokens,
 };
 //# sourceMappingURL=help-json-payload.js.map
-//# debugId=42b9782e-2151-54b0-98ce-8c5ae810c424
+//# debugId=abdb8d3e-8c1b-511e-b25b-220d5a40ae3f

package/dist/cli/main.js

@@ -3,7 +3,7 @@
  * @module cli/main
  */
 
-!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]="cf9d1c78-06f0-5330-8562-ac863c95ee86")}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]="27eeca2d-756c-539b-a0d4-d64516ee4aa6")}catch(e){}}();
 import { Command } from "commander";
 import { activateExtensions, clearActiveExtensionHooks, createCoreCommandHookContext, resetActiveExtensionRuntimeState, createEmptyExtensionRegistrationRegistry, discoverExtensions, getActiveCommandResult, getActiveExtensionRegistrations, loadExtensions, consumeAfterCommandAffectedItems, runActiveCommandHandler, runActiveParserOverride, runActivePreflightOverride, runAfterCommandHooks, runBeforeCommandHooks, setActiveCommandResult, setActiveCommandContext, setActiveExtensionCommands, setActiveExtensionHooks, setActiveExtensionParsers, setActiveExtensionPreflight, setActiveExtensionRegistrations, setActiveExtensionRenderers, setActiveExtensionServices, pathExists, resolvePmCliVersion, resolvePmPackageRootFromModule, resolveItemTypeRegistry, resolveRuntimeFieldRegistry, EXIT_CODE, resolveTelemetryErrorCategory, PmCliError, asRecordOrNull, printError, printResult, maybeRunFirstUseTelemetryPrompt, emitTelemetryErrorEvent, startTelemetryCommand, deriveTelemetryCommandResolution, sentryCaptureCliError, sentryFinishCommandSpan, sentryFlush, sentryLogCliUsageError, sentrySetCommandContext, sentryStartCommandSpan, ensureSentryInit, getSettingsPath, resolvePmRoot, readSettings, readSettingsWithMetadata, runWithWorkspaceHarnessSignalDescriptors, createLazyModule, } from "../sdk/runtime-primitives.js";
 import { resolveSubcommandFlagContractsForCommand } from "../sdk/cli-contracts.js";
@@ -138,6 +138,7 @@ function projectExistingRecoveryOptionalFields(existingRecovery) {
         "recovery_mode",
         "missing_required_fields",
         "suggested_flags",
+        "suggested_retry_args",
         "allowed_values",
         "candidate_commands",
         "candidate_commands_total",
@@ -182,6 +183,9 @@ function buildPmCliRecoveryContext(context, invocationArgv, rawMessage) {
             ...(rawExistingRecovery.suggested_retry
                 ? { suggested_retry: renderAttemptedCommand(safeInvocationArgv) }
                 : {}),
+            ...(rawExistingRecovery.suggested_retry_args
+                ? { suggested_retry_args: [...safeInvocationArgv] }
+                : {}),
         }
         : rawExistingRecovery;
     if (existingRecovery?.recovery_mode === "compact" && !explainRequested) {
@@ -2512,4 +2516,4 @@ export const _testOnly = {
     wrapThrownErrorForSentry,
 };
 //# sourceMappingURL=main.js.map
-//# debugId=cf9d1c78-06f0-5330-8562-ac863c95ee86
+//# debugId=27eeca2d-756c-539b-a0d4-d64516ee4aa6

package/dist/cli/register-list-query.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7bcf441b-e211-535f-9502-5624add292e5")}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]="d3206ea9-3bf7-5e23-8b95-2a9078942b6f")}catch(e){}}();
 import { EXIT_CODE, PmCliError, readSettings, renderRowsAsCsv, renderRowsAsTable, resolvePmRoot, } from "../sdk/runtime-primitives.js";
 import { renderPmCommandAliasMigrationHint, resolvePmCommandAlias, } from "../sdk/cli-contracts.js";
 import { EVAL_QUERY_SET_SCHEMA_ID } from "../sdk/eval.js";
@@ -334,9 +334,12 @@ async function runNextAction(options, actionCommand) {
 async function runSearchAction(keywords, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    const intentOptions = applyContextIntentProjection("search", options);
+    const query = normalizeSearchKeywordsInput(keywords);
+    const intentOptions = applyContextIntentProjection("search", options, [
+        query,
+    ]);
     const searchOptions = normalizeSearchOptions(intentOptions);
-    const result = await runSearch(normalizeSearchKeywordsInput(keywords), {
+    const result = await runSearch(query, {
         ...searchOptions,
         mode: typeof searchOptions.mode === "string" &&
             searchOptions.mode.trim().length > 0
@@ -382,7 +385,7 @@ async function runEvalAction(options, command) {
 async function runGetAction(id, options, command) {
     const globalOptions = getGlobalOptions(command);
     const startedAt = Date.now();
-    const intentOptions = applyContextIntentProjection("get", options);
+    const intentOptions = applyContextIntentProjection("get", options, [id]);
     const result = await runGet(id, globalOptions, {
         depth: typeof intentOptions.depth === "string" ? intentOptions.depth : undefined,
         fields: typeof intentOptions.fields === "string"
@@ -919,4 +922,4 @@ export const _testOnlyRegisterListQuery = {
     parseListFormat,
 };
 //# sourceMappingURL=register-list-query.js.map
-//# debugId=7bcf441b-e211-535f-9502-5624add292e5
+//# debugId=d3206ea9-3bf7-5e23-8b95-2a9078942b6f

package/dist/cli/register-mutation.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7feb0fe0-386c-56dc-afe1-e7b4ce1bc95a")}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]="07f3212f-c6d3-534e-8273-fae43a8fca18")}catch(e){}}();
 import { resolveBodyFileContent, EXIT_CODE, splitCommaList, PmCliError, createUnknownSubcommandError, } from "../sdk/runtime-primitives.js";
 import { CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, PLAN_CREATE_METADATA_PARAMETER_KEYS, UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS, } from "../sdk/cli-contracts.js";
 import { BUILTIN_ITEM_TYPE_VALUES, PLAN_STEP_LINK_KIND_VALUES, } from "../types/index.js";
@@ -1233,7 +1233,7 @@ async function runDepsAction(id, options, command) {
 export function registerMutationCommands(program, registrationOptions = {}) {
     const createCommand = program
         .command("create")
-        .argument("[typeOrTitle]", 'Item title, or item type when a title follows (e.g. `pm create task "Fix bug"`)')
+        .argument("[type-or-title]", 'Item title, or item type when a title follows (e.g. `pm create task "Fix bug"`)')
         .argument("[title]", "Item title when the first argument is an item type")
         .description("Create a new project management item.");
     registerCommanderOptionContracts(createCommand, CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS);
@@ -1530,10 +1530,10 @@ export function registerMutationCommands(program, registrationOptions = {}) {
     const planCommand = program
         .command("plan")
         .description("Agent-optimized Plan item workflow: create, manage steps, link dependencies, approve, and materialize.")
-        .argument("[subcommand]", "Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize")
+        .argument("[subcommand]", "Required; Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize")
         .argument("[id]", "Plan id (required for non-create subcommands); for create this may be the positional title")
-        .argument("[stepRef]", "Step reference: stable id (plan-step-001) or order integer")
-        .argument("[reorderTo]", "New order integer for reorder-step")
+        .argument("[step]", "Step reference: stable id (plan-step-001) or order integer")
+        .argument("[new-order]", "New order integer for reorder-step")
         .option("--title <value>", "Plan title")
         .option("--description <value>", "Plan description")
         .option("--scope <value>", "Short scope statement of the target change or investigation")
@@ -1740,7 +1740,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runMergeAction);
     const schemaCommand = program
         .command("schema")
-        .argument("[subcommand]", "Schema subcommand: list, show, show-status, add/remove type/status/field, rename-type, rename-field, remap-status, or a custom item type name shorthand")
+        .argument("[subcommand]", "Required; Schema subcommand: list, show, show-status, add/remove type/status/field, rename-type, rename-field, remap-status, or a custom item type name shorthand")
         .argument("[name]", "Definition name, or source name for rename/remap migrations")
         .option("--description <text>", "Human description for the custom item type, status, or field")
         .option("--default-status <status>", "Default status hint recorded for the custom item type")
@@ -1770,7 +1770,7 @@ export function registerMutationCommands(program, registrationOptions = {}) {
     schemaCommand.action(runSchemaAction);
     const profileCommand = program
         .command("profile")
-        .argument("[subcommand]", "Profile subcommand: list, show, apply, or lint")
+        .argument("[subcommand]", "Required; Profile subcommand: list, show, apply, or lint")
         .argument("[name]", "Profile name for show/apply/lint: agile, ops, or research")
         .option("--dry-run", "Preview the apply diff without writing any files (apply)")
         .option("--author <value>", "Mutation author")
@@ -1840,4 +1840,4 @@ export function registerMutationCommands(program, registrationOptions = {}) {
         .action(runDepsAction);
 }
 //# sourceMappingURL=register-mutation.js.map
-//# debugId=7feb0fe0-386c-56dc-afe1-e7b4ce1bc95a
+//# debugId=07f3212f-c6d3-534e-8273-fae43a8fca18

package/dist/cli/register-operations.js

@@ -1,9 +1,9 @@
 
-!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]="dec5fb7d-416f-5da6-bd97-c05c25dbf769")}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]="975321a1-0375-5829-a012-f23e32e9c6bf")}catch(e){}}();
 import { resolveRuntimeStatusRegistry, setActiveCommandResult, EXIT_CODE, PmCliError, createUnknownSubcommandError, resolveAuthor, resolvePmRoot, readSettings, } from "../sdk/runtime-primitives.js";
 import { resolveStartTaskInProgressStatus } from "../sdk/start-task-status.js";
 import { parseStatsAnalyticsJson } from "./stats-analytics-json.js";
-import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, } from "../sdk/workspace-snapshot.js";
+import { createWorkspaceSnapshot, deleteWorkspaceSnapshot, inspectWorkspaceSnapshot, listWorkspaceSnapshots, planWorkspaceSnapshotRestore, restoreWorkspaceSnapshotWithRecovery, WORKSPACE_SNAPSHOT_ACTIONS, } from "../sdk/workspace-snapshot.js";
 import { runClaim, runClaimNext, runRelease } from "./commands/claim.js";
 import { runClose } from "./commands/close.js";
 import { runContracts } from "./commands/contracts.js";
@@ -380,11 +380,11 @@ async function runWorkspaceSnapshotAction(action, target, options, command) {
     const globalOptions = getGlobalOptions(command);
     const pmRoot = resolvePmRoot(process.cwd(), globalOptions.path);
     const normalizedAction = action.trim().toLowerCase();
-    if (!["create", "list", "inspect", "restore", "delete"].includes(normalizedAction)) {
+    if (!WORKSPACE_SNAPSHOT_ACTIONS.some((entry) => entry === normalizedAction)) {
         throw createUnknownSubcommandError({
             command_path: "workspace snapshot",
             token: action,
-            allowed: ["create", "list", "inspect", "restore", "delete"],
+            allowed: WORKSPACE_SNAPSHOT_ACTIONS,
             display_name: "workspace snapshot",
             token_kind: "action",
             examples: [
@@ -606,7 +606,7 @@ export function registerOperationCommands(program) {
     });
     program
         .command("telemetry")
-        .argument("[namespaceOrSubcommand]", "Telemetry subcommand: status, flush, stats, clear (default: status)")
+        .argument("[namespace-or-subcommand]", "Telemetry subcommand: status, flush, stats, clear (default: status)")
         .argument("[subcommand]", "Compatibility alias target for local-analytics: status, flush, stats, clear")
         .option("--limit <n>", "Maximum command groups returned by telemetry stats")
         .description("Inspect and manage local telemetry queue/runtime state.")
@@ -873,4 +873,4 @@ function registerSchedulingShortcutCommands(program) {
     });
 }
 //# sourceMappingURL=register-operations.js.map
-//# debugId=dec5fb7d-416f-5da6-bd97-c05c25dbf769
+//# debugId=975321a1-0375-5829-a012-f23e32e9c6bf