@unbrained/pm-cli 2026.8.17 → 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.17"
+    "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.17",
+      "version": "2026.8.19",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/AGENTS.md

@@ -63,8 +63,8 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm create --create-mode progressive --title "..." --description "..." --type Task --status open
 pm claim <id>
 pm update <id> --status in_progress --message "Start implementation"
@@ -82,12 +82,13 @@ Author identity is automatic; use `--author` only for an explicit override.
 
 ## Working Rules
 
-- **Orient:** run `pm context`, `pm search`, `pm list-open`, and `pm list-in-progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
+- **Orient:** run `pm context`, `pm search`, `pm list --status open`, and `pm list --status in_progress` before `pm create`. If net-new work is required, create or reuse the parent lineage first and record duplicate-check evidence in a create-time comment.
 - **Verify before you claim:** the verification recipe for the Non-Negotiable above. A `closed` item whose `resolution`/`close_reason` describes the fix represents completed, shipped work — never describe it as outstanding. Confirm release/CI/infra status against the live system, e.g. `pm get pm-9gxi`, `npm view @unbrained/pm-cli version`, `gh release list`, `gh run list --workflow=auto-release.yml`.
 - **Implement:** keep edits scoped to the claimed item. Link changed files with `pm files`, docs with `pm docs`, and runnable verification with `pm test`.
 - **Record:** use `pm comments`, `pm notes`, and `pm learnings` for progress, rationale, and durable lessons. Prefer append-style updates over rewriting item content.
 - **Verify:** use sandbox-safe commands. For documentation-only work, run at least `pnpm build` and a focused link/content check. For broader work, run linked tests, coverage, validation, and release gates as appropriate.
 - **Close:** add evidence first, then `pm close <id> "<reason>" --validate-close warn`, then `pm release <id>`.
+- **Land closeout through review:** tracker evidence, item closure, and the generated changelog are part of the reviewed delivery. Never push post-merge closeout commits directly to `main`; if evidence depends on the merge SHA, carry it in a normal `main`-based follow-up PR so the new head retains analyzer provenance. See [Releasing](docs/RELEASING.md#reviewed-delivery-closeout).
 
 ## Test Safety
 

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # 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
+
+- Alias shim layer: config-aware hidden aliases with one-line migration hints (foundation for all consolidations) ([pm-0z7n](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-0z7n.toon))
+
+### Fixed
+
+- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
+- GH-1052: typed fail-closed whole-list SDK primitive ([pm-y4aaol](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4aaol.toon))
+- Packed Bun SDK import fails on node:module stripTypeScriptTypes ([pm-ikj8ve](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ikj8ve.toon))
+- GH-1051: package catalog rejects universal output-budget controls ([pm-2firut](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2firut.toon))
+- Bun event streaming falls back to authoritative history without node:sqlite ([pm-b8hwfr](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-b8hwfr.toon))
+- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
+- CodeQL: remove generated-code artifact path interpolation from exporter integration harness ([pm-ozxkm2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ozxkm2.toon))
+- Exporter artifact-channel contract: clean stdout, bounded receipts, and binary-safe streaming ([pm-dilou2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dilou2.toon))
+- GH-1048: Windows Node 24 numeric EDQUOT fixtures construct NaN on platforms that do not declare that errno ([pm-y4kovm](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4kovm.toon))
+- Queued daily releases recognize an already-published same-day release before analyzer provenance ([pm-dm2vfz](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-dm2vfz.toon))
+
+### Security
+
+- Adopt Dependabot PR \#1046 pinned CodeQL 4.37.7 and TruffleHog 3.97.0 refresh ([pm-pp6al9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-pp6al9.toon))
+
+### Deprecated
+
+- ADR: noun-verb CLI grammar — accepted consolidation principles and alias-preserving deprecation policy ([pm-pbyu](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/decisions/pm-pbyu.toon))
+
+### Other
+
+- Command-grammar conformance gate: the noun-verb table and shared verb vocabulary become machine-checked contracts a non-conforming command cannot pass ([pm-wt43zj](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-wt43zj.toon))
+- Consolidate the 8 list-\* status variants into pm list --status (list-all/open/draft/in-progress/blocked/closed/canceled become hidden aliases) ([pm-pfqi](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-pfqi.toon))
+- Command-destination census: 14 of 76 canonical commands have no declared home in the target grammar, so the surface can be frozen with its shape still undecided ([pm-yy8rmx](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-yy8rmx.toon))
+- Half of the pm events payload is per-row resume cursors an agent never reads: 48 percent of stream bytes buy a capability consumed once per batch ([pm-ez1dfg](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-ez1dfg.toon))
+
 ## 2026.8.17 - 2026-08-17
 
 ### Added
@@ -37,7 +87,6 @@
 - GH-1028: history-author-acknowledge bulk mutation lacks dry-run and misreports empty selection ([pm-mcxk8v](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mcxk8v.toon))
 - GH-1030: contracts --json --full is wholly omitted by the default output budget ([pm-2qvq7a](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-2qvq7a.toon))
 - Auto Release blocker closure ignores successful recovery dispatch and reruns the stale tag-push workflow ([pm-db8onn](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-db8onn.toon))
-- A commit pushed directly to the default branch can never be released: both analyzer-evidence fallbacks presuppose a pull request, and nothing declares that precondition ([pm-u1baah](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-u1baah.toon))
 
 ### Other
 
@@ -52,11 +101,9 @@
 - Provide an audited repair and severity-migration contract for legacy invalid provenance ([pm-76fkpp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-76fkpp.toon))
 - Detect extension-host pm-cli version skew before a workspace reports healthy ([pm-643e0k](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-643e0k.toon))
 - Restore strict unknown-key parity for docs linked-artifact additions ([pm-22rzjp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-22rzjp.toon))
-- Surface replication gate scopes trigger activation to relevant diff content ([pm-mrhwow](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-mrhwow.toon))
 - 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))
@@ -519,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))
@@ -969,10 +1015,10 @@
 
 ### Fixed
 
+- Sentry no longer captures deliberate Ctrl+C/Ctrl+D interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - pm get --full omits children for Plan parents while pm list --parent returns them ([pm-y4z5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-y4z5.toon))
 - Intentional package CommandError outcomes create high-severity Sentry issues (PM-CLI-16) ([pm-7071](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7071.toon))
 - Extension install self-copy guard: reject source-inside-destination layouts before fs.cp EINVAL (PM-CLI-28) ([pm-8myl](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-8myl.toon))
-- Sentry captures deliberate Ctrl+C interrupts as error-level events (AbortError, PM-CLI-27) ([pm-ksv2](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-ksv2.toon))
 - Torn-install bundle transients block scheduled releases: boot-time chunk-integrity self-check + distinct error code for gate classification ([pm-wfvq](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-wfvq.toon))
 - GH-446: pm get omits schedule facet (events/start_at/end_at/location) for Meeting/Event/Reminder ([pm-x1g5](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-x1g5.toon))
 - GH-533: create/update accept empty --title — required-title contract inconsistent between omitted and empty string ([pm-7je0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-7je0.toon))

package/README.md

@@ -84,7 +84,7 @@ pm create \
   --ac "Restore succeeds after stale lock cleanup and has regression coverage." \
   --create-mode progressive
 
-pm list-open --limit 10
+pm list --status open --limit 10
 pm claim <item-id>
 pm update <item-id> --status in_progress --message "Start implementation"
 pm files <item-id> --add path=src/core/lock/lock.ts
@@ -102,8 +102,8 @@ Use `pm next` to get the single highest-priority ready item (and why), or `pm co
 pm next                                          # the next actionable item + rationale, ready/blocked queues
 pm context --limit 10
 pm search "keywords for the requested work" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 If no relevant item exists, create a parent lineage before child work, claim the child item, link changed files/docs/tests, and leave evidence comments before closing. The full workflow is in the [Agent Guide](docs/AGENT_GUIDE.md).

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]="5251395b-715a-5559-a7d5-ca3bc4a1bb16")}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) {
@@ -483,7 +484,7 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
     const nextSteps = isPlaceholder
         ? [
             "Check that the variable holding the item ID is defined before passing it to pm.",
-            'Use "pm list-open --limit 20" to find valid IDs.',
+            'Use "pm list --status open --limit 20" to find valid IDs.',
         ]
         : ["Confirm the active --path/PM_PATH scope, then retry with a valid id."];
     return applyPmCliErrorContext(makeGuidanceMessage({
@@ -492,7 +493,10 @@ function buildItemNotFoundGuidance(rawMessage, message, context) {
         happened,
         required: "Use an existing item ID from current tracker data.",
         why: "Mutation and read commands operate only on known IDs.",
-        examples: ["pm list-open --limit 20", 'pm search "<keyword>" --limit 10'],
+        examples: [
+            "pm list --status open --limit 20",
+            'pm search "<keyword>" --limit 10',
+        ],
         nextSteps,
     }), rawMessage, context);
 }
@@ -1237,4 +1241,4 @@ export const _testOnly = {
     resolveKnownPackageCommandHint,
 };
 //# sourceMappingURL=error-guidance.js.map
-//# debugId=5251395b-715a-5559-a7d5-ca3bc4a1bb16
+//# 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