@unbrained/pm-cli 2026.10.15 → 2026.10.18

package/.agents/skills/pm-developer/references/COMMAND_PLAYBOOK.md

@@ -45,7 +45,7 @@ pm close-many --ids <ID>,<ID> --reason "<shared reason>" --dry-run
 pm test <ID> --run --progress
 node scripts/run-tests.mjs coverage
 pm comments <ID> "Evidence: linked tests passed; coverage remained green."
-pm close <ID> "Acceptance criteria met with verification evidence." --validate-close warn
+pm close <ID> "Verified" --resolution "Delivered change" --expected "Required outcome" --actual "Observed outcome" --validate-close warn
 pm release <ID>
 ```
 

package/.claude-plugin/marketplace.json

@@ -1 +1 @@
-{"name":"pm","owner":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"description":"Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.","version":"2026.10.15","plugins":[{"name":"pm-claude","source":"./plugins/pm-claude","description":"Native pm CLI integration for Claude Code — 32 MCP tools, 14 workflow skills with slash invocations, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.","version":"2026.10.15","author":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"homepage":"https://github.com/unbraind/pm-cli","repository":"https://github.com/unbraind/pm-cli","license":"MIT","keywords":["pm-cli","project-management","mcp","tasks","agents","workflows","git-native","task-tracker","ai"],"category":"productivity"}]}
+{"name":"pm","owner":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"description":"Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.","version":"2026.10.18","plugins":[{"name":"pm-claude","source":"./plugins/pm-claude","description":"Native pm CLI integration for Claude Code — 32 MCP tools, 14 workflow skills with slash invocations, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.","version":"2026.10.18","author":{"name":"unbrained","url":"https://github.com/unbraind/pm-cli"},"homepage":"https://github.com/unbraind/pm-cli","repository":"https://github.com/unbraind/pm-cli","license":"MIT","keywords":["pm-cli","project-management","mcp","tasks","agents","workflows","git-native","task-tracker","ai"],"category":"productivity"}]}

package/AGENTS.md

@@ -89,6 +89,7 @@ For real repository tracking, do not override `PM_PATH`. If a script must target
 
 - Keep this file and [README](README.md) short.
 - Move details into focused docs under `docs/` and keep links relative/GitHub-compatible.
+- Packaged pages may use canonical GitHub file URLs for repository-only files intentionally excluded from npm. State that exclusion beside the link; keep links between packaged pages relative.
 - Add tracker references near the top of new docs when a `pm` item created the change.
 - Link documentation changes back to the active item with `pm docs`.
 

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 2026.10.18 - 2026-10-18
+
+### Fixed
+
+- Retain tested optional-peer closures in the published runtime bundle ([pm-iceees](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-iceees.toon))
+- Fail the required coverage aggregate when any shard fails or is skipped ([pm-0p4aal](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-0p4aal.toon))
+- Invalidate shared history projections when writers lack SQLite ([pm-f7shxf](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-f7shxf.toon))
+- GH-1485: Bound history-index reader contention before authoritative appends ([pm-gh1485](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1485.toon))
+- Keep mutation-event subscriptions available when optional index rebuilds race or contend ([pm-xj80p9](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-xj80p9.toon))
+- GH-1487: Respect nested Git repository boundaries during tracker discovery ([pm-gh1487](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1487.toon))
+- GH-1484: Infer native Node test telemetry and bound intentional test flush lifetime ([pm-gh1484](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1484.toon))
+- GH-1486: Keep passing health diagnostics concise by default ([pm-gh1486](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1486.toon))
+- GH-1489: Keep all-status list filters independent of field projection ([pm-gh1489](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1489.toon))
+- GH-1482: Read legacy dependency timestamps safely and diagnose invalid values ([pm-gh1482](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1482.toon))
+- GH-1481: Retain explicitly requested sort values in brief list projections ([pm-gh1481](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1481.toon))
+
+### Other
+
+- Adopt immutable TruffleHog 3.98.0 after the release-age boundary ([pm-38w3ii](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-38w3ii.toon))
+- Renew pinned pnpm Windows shell-launcher compatibility after dependency cooldown ([pm-rnpmtp](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-rnpmtp.toon))
+- Refresh compatible Sentry 10.76.2 observability patch ([pm-wejmmy](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-wejmmy.toon))
+- Refresh seven-day-eligible Greptile 3.6.2 review tooling ([pm-8jhc84](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-8jhc84.toon))
+- Qualify real-baseline checks and packed concurrent-create acceptance across runtimes ([pm-58zon0](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-58zon0.toon))
+- Refresh eligible October 17 dependencies with SDK codec compatibility proof ([pm-ul0ow4](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/chores/pm-ul0ow4.toon))
+
+## 2026.10.17 - 2026-10-17
+
+### Added
+
+- GH-1456: Discoverable SDK-backed bulk creation with JSONL and keyed upsert ([pm-gh1456](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-gh1456.toon))
+- Validate contributed scalar flag values before extension handler dispatch ([pm-extension-scalar-validation](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-extension-scalar-validation.toon))
+- GH-1465: Represent implementer-to-verifier handoff as project context ([pm-gh1465](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/features/pm-gh1465.toon))
+
+### Fixed
+
+- Preserve surrogate pairs in bounded JSON and TOON output ([pm-gh1478](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1478.toon))
+- Refuse item text with an unpaired surrogate as a typed field error before TOON encoding ([pm-jsm9im](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-jsm9im.toon))
+- Return typed refusals for malformed raw duration options ([pm-bulk-option-validation](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-bulk-option-validation.toon))
+- Align claim guidance with atomic ownership refusal ([pm-5f7ayv](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-5f7ayv.toon))
+- GH-1464: Distinguish successful close follow-up from failure recovery ([pm-gh1464](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1464.toon))
+
+### Other
+
+- As an MCP host or coding agent, I can discover pm capabilities and complete long-running context workflows through one current stateless protocol ([pm-x705zo](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/stories/pm-x705zo.toon))
+
 ## 2026.10.15 - 2026-10-15
 
 ### Fixed

package/dist/cli/extension-command-options.d.ts

@@ -20,13 +20,15 @@ list?:boolean;
 repeatable?:boolean;
 /** Value used when callers omit the option. */
 default?:unknown;
+/** `strict` refuses malformed number/boolean tokens before dispatch; `coerce` (default) forwards them. */
+value_validation?:string;
 }
 /** Implements collect loose command option keys for definitions for the public runtime surface of this module. */
 export declare function collectLooseCommandOptionKeysForDefinitions(definitions:ReadonlyArray<LooseCommandFlagDefinition>):Set<string>;
 /** Implements validate loose command options with flag definitions for the public runtime surface of this module. */
 export declare function validateLooseCommandOptionsWithFlagDefinitions(options:Record<string,unknown>,definitions:ReadonlyArray<LooseCommandFlagDefinition>,commandPath:string):void;
 /** Implements coerce loose command options with flag definitions for the public runtime surface of this module. */
-export declare function coerceLooseCommandOptionsWithFlagDefinitions(options:Record<string,unknown>,definitions:ReadonlyArray<LooseCommandFlagDefinition>,occurrenceSource?:Record<string,unknown>):Record<string,unknown>;
+export declare function coerceLooseCommandOptionsWithFlagDefinitions(options:Record<string,unknown>,definitions:ReadonlyArray<LooseCommandFlagDefinition>,occurrenceSource?:Record<string,unknown>,commandPath?:string):Record<string,unknown>;
 /** Implements parse loose command options for the public runtime surface of this module. */
 export declare function parseLooseCommandOptions(args:string[]):Record<string,unknown>;
 /** Returns the positional operands in `args`, skipping option tokens and the values they consume (`--flag value`, `--flag=value`, `-f value`, and boolean flags). Tokens after a bare `--` separator are all positional. Used to count genuinely unexpected positionals for extension commands that declare no arguments without miscounting leaked/undeclared option tokens as operands. */

package/dist/cli/extension-command-options.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0e7ed11b-0194-53e5-8b2d-d7d91f295b8a")}catch{}})();import{resolveExtensionLongFlagName,EXIT_CODE,PmCliError,flattenFlagListValue,resolveFlagValueKind}from"../sdk/runtime-primitives.js";const UNSAFE_LOOSE_OPTION_KEYS=new Set(["__proto__","prototype","constructor"]),LOOSE_OPTION_OCCURRENCES=Symbol("looseOptionOccurrences");function toLooseOptionKey(rawKey){return rawKey.trim().toLowerCase().replaceAll(/-([a-z0-9])/g,(_match,group)=>group.toUpperCase())}function setLooseOptionValue(options,key,value){const existing=options[key];if(existing===void 0){options[key]=value;return}if(Array.isArray(existing)){existing.push(value),options[key]=existing;return}options[key]=[existing,value]}function parseLooseOptionToken(args,index){const token=args[index];if(!token.startsWith("-")||token==="-"||token==="--")return null;if(!token.startsWith("--")){const equalsIndex2=token.indexOf("=");if(equalsIndex2>=0)return{consumed:1,key:token.slice(1,equalsIndex2).trim(),value:token.slice(equalsIndex2+1)};const key2=token.slice(1).trim(),next2=args[index+1];return typeof next2=="string"&&!next2.startsWith("-")?{consumed:2,key:key2,value:next2}:{consumed:1,key:key2,value:!0}}const equalsIndex=token.indexOf("=");if(equalsIndex>=0)return{consumed:1,key:token.slice(2,equalsIndex).trim(),value:token.slice(equalsIndex+1)};if(token.startsWith("--no-"))return{consumed:1,key:token.slice(5).trim(),value:!1};const key=token.slice(2).trim(),next=args[index+1];return typeof next=="string"&&!next.startsWith("-")?{consumed:2,key,value:next}:{consumed:1,key,value:!0}}function isUnsafeLooseOptionKey(key){return UNSAFE_LOOSE_OPTION_KEYS.has(key)}function resolveLooseOptionCoercionKind(definition){const raw=(typeof definition.value_type=="string"?definition.value_type:void 0)??(typeof definition.type=="string"?definition.type:void 0);return resolveFlagValueKind(raw)}function collectLooseOptionKeys(definition){const keys=[],long=resolveExtensionLongFlagName(definition.long)??"",short=typeof definition.short=="string"?definition.short.trim():"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}if(short.startsWith("-")&&!short.startsWith("--")){const normalized=toLooseOptionKey(short.slice(1));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}return[...new Set(keys)]}function collectLooseCommandOptionKeysForDefinitions(definitions){const keys=new Set;for(const definition of definitions)for(const key of collectLooseOptionKeys(definition))keys.add(key);return keys}function resolveCanonicalLooseOptionKey(definition){const long=resolveExtensionLongFlagName(definition.long)??"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));if(normalized.length>0&&!isUnsafeLooseOptionKey(normalized))return normalized}return collectLooseOptionKeys(definition)[0]??null}function formatLooseOptionLabel(definition){const long=typeof definition.long=="string"?definition.long.trim():"";if(long.startsWith("--")&&long.length>2)return long;const short=typeof definition.short=="string"?definition.short.trim():"";return short.startsWith("-")&&!short.startsWith("--")&&short.length>1?short:null}function validateLooseCommandOptionsWithFlagDefinitions(options,definitions,commandPath){if(definitions.length===0)return;const allowed=new Set,disabled=new Map,required=[],labels=[];for(const definition of definitions){const keys=collectLooseOptionKeys(definition),normalizedLabel=formatLooseOptionLabel(definition);normalizedLabel!==null&&labels.push(normalizedLabel);for(const key of keys)allowed.add(key),definition.enabled===!1&&disabled.set(key,normalizedLabel);definition.required===!0&&definition.enabled!==!1&&keys.length>0&&required.push({keys,label:normalizedLabel})}for(const key of Object.keys(options)){if(!allowed.has(key)){const expected=labels.length>0?` Expected one of: ${[...new Set(labels)].join(", ")}.`:"";throw new PmCliError(`Unknown option '--${key}' for extension command '${commandPath}'.${expected}`,EXIT_CODE.USAGE)}const disabledLabel=disabled.get(key);if(disabledLabel)throw new PmCliError(`Option '${disabledLabel}' is disabled for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}for(const entry of required)if(!entry.keys.some(key=>Object.hasOwn(options,key)))throw new PmCliError(`Missing required option '${entry.label}' for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}function coerceLooseStringOptionValue(value){return typeof value=="string"||value==null?value:String(value)}function coerceLooseNumberOptionValue(value){if(typeof value=="number")return value;if(typeof value=="string"&&value.trim().length>0){const parsed=Number(value);return Number.isFinite(parsed)?parsed:value}return value}function coerceLooseBooleanOptionValue(value){if(typeof value=="boolean")return value;if(typeof value=="string"){const normalized=value.trim().toLowerCase();if(normalized==="true"||normalized==="1")return!0;if(normalized==="false"||normalized==="0")return!1}return value}const LOOSE_OPTION_VALUE_COERCERS={string:coerceLooseStringOptionValue,number:coerceLooseNumberOptionValue,boolean:coerceLooseBooleanOptionValue};function coerceLooseOptionValue(value,kind){return Array.isArray(value)?value.map(entry=>coerceLooseOptionValue(entry,kind)):LOOSE_OPTION_VALUE_COERCERS[kind](value)}function normalizeAccumulatedFlagValue(value,kind,preserveOccurrenceCommas){const entries=preserveOccurrenceCommas?(Array.isArray(value)?value.flat(1/0):[value]).filter(entry=>entry!=null&&entry!==""):flattenFlagListValue(value);return kind?entries.map(entry=>coerceLooseOptionValue(entry,kind)):entries}function applyFlagDefault(defaultValue,kind,isListFlag,preserveOccurrenceCommas){return isListFlag?normalizeAccumulatedFlagValue(defaultValue,kind,preserveOccurrenceCommas):kind?coerceLooseOptionValue(defaultValue,kind):defaultValue}function readOrderedLooseListValues(occurrenceSource,optionKeys,fallback){const occurrences=occurrenceSource[LOOSE_OPTION_OCCURRENCES];if(!occurrences||occurrences.length===0)return fallback;const acceptedKeys=new Set(optionKeys);return occurrences.filter(occurrence=>acceptedKeys.has(occurrence.key)).map(occurrence=>occurrence.value)}function coerceLooseCommandOptionsWithFlagDefinitions(options,definitions,occurrenceSource=options){if(definitions.length===0)return options;const coerced=Object.create(null);for(const[key,value]of Object.entries(options))coerced[key]=value;for(const definition of definitions){const canonical=resolveCanonicalLooseOptionKey(definition);if(!canonical)continue;const isListFlag=definition.list===!0,optionKeys=collectLooseOptionKeys(definition);for(const key of optionKeys)if(!(key===canonical||!Object.hasOwn(coerced,key))){if(Object.hasOwn(coerced,canonical)){if(!isListFlag){delete coerced[key];continue}const canonicalValue=coerced[canonical],aliasValue=coerced[key];coerced[canonical]=[...Array.isArray(canonicalValue)?canonicalValue:[canonicalValue],...Array.isArray(aliasValue)?aliasValue:[aliasValue]].filter(value=>value!=null),delete coerced[key];continue}coerced[canonical]=coerced[key],delete coerced[key]}const kind=resolveLooseOptionCoercionKind(definition),preserveOccurrenceCommas=definition.repeatable===!0;if(!Object.hasOwn(coerced,canonical)){definition.default!==void 0&&(coerced[canonical]=applyFlagDefault(definition.default,kind,isListFlag,preserveOccurrenceCommas));continue}if(isListFlag){coerced[canonical]=normalizeAccumulatedFlagValue(readOrderedLooseListValues(occurrenceSource,optionKeys,coerced[canonical]),kind,preserveOccurrenceCommas);continue}kind&&(coerced[canonical]=coerceLooseOptionValue(coerced[canonical],kind))}return coerced}function parseLooseCommandOptions(args){const options=Object.create(null),occurrences=[];Object.defineProperty(options,LOOSE_OPTION_OCCURRENCES,{value:occurrences});let index=0;for(;index<args.length;){const parsed=parseLooseOptionToken(args,index);if(!parsed){index+=1;continue}const normalizedKey=toLooseOptionKey(parsed.key);if(normalizedKey.length===0||isUnsafeLooseOptionKey(normalizedKey)){index+=parsed.consumed;continue}setLooseOptionValue(options,normalizedKey,parsed.value),occurrences.push({...parsed,key:normalizedKey}),index+=parsed.consumed}return options}function collectLoosePositionalArgs(args){const positionals=[];let index=0;for(;index<args.length;){if(args[index]==="--"){positionals.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){index+=Math.max(1,parsed.consumed);continue}positionals.push(args[index]),index+=1}return positionals}function stripLooseCommandOptionTokens(args,definitions){if(definitions.length===0)return[...args];const knownKeys=new Set,booleanKeys=new Set;for(const definition of definitions){const valueKind=resolveLooseOptionCoercionKind(definition);for(const key of collectLooseOptionKeys(definition))knownKeys.add(key),valueKind==="boolean"&&booleanKeys.add(key)}if(knownKeys.size===0)return[...args];const stripped=[];let index=0;for(;index<args.length;){if(args[index]==="--"){stripped.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){const normalizedKey=toLooseOptionKey(parsed.key);if(knownKeys.has(normalizedKey)){const token=args[index],consumed=booleanKeys.has(normalizedKey)&&!token.includes("=")?1:parsed.consumed;index+=consumed;continue}}stripped.push(args[index]),index+=1}return stripped}export{coerceLooseCommandOptionsWithFlagDefinitions,collectLooseCommandOptionKeysForDefinitions,collectLoosePositionalArgs,parseLooseCommandOptions,stripLooseCommandOptionTokens,validateLooseCommandOptionsWithFlagDefinitions};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c6ed71d0-b878-575e-b990-356afdc45688")}catch{}})();import{describeFlagScalarValueFailure,resolveExtensionFlagValueContract,resolveExtensionLongFlagName,EXIT_CODE,PmCliError,flattenFlagListValue,resolveFlagValueKind}from"../sdk/runtime-primitives.js";const UNSAFE_LOOSE_OPTION_KEYS=new Set(["__proto__","prototype","constructor"]),LOOSE_OPTION_OCCURRENCES=Symbol("looseOptionOccurrences");function toLooseOptionKey(rawKey){return rawKey.trim().toLowerCase().replaceAll(/-([a-z0-9])/g,(_match,group)=>group.toUpperCase())}function setLooseOptionValue(options,key,value){const existing=options[key];if(existing===void 0){options[key]=value;return}if(Array.isArray(existing)){existing.push(value),options[key]=existing;return}options[key]=[existing,value]}function parseLooseOptionToken(args,index){const token=args[index];if(!token.startsWith("-")||token==="-"||token==="--")return null;if(!token.startsWith("--")){const equalsIndex2=token.indexOf("=");if(equalsIndex2>=0)return{consumed:1,key:token.slice(1,equalsIndex2).trim(),value:token.slice(equalsIndex2+1),attached:!0};const key2=token.slice(1).trim(),next2=args[index+1];return typeof next2=="string"&&!next2.startsWith("-")?{consumed:2,key:key2,value:next2}:{consumed:1,key:key2,value:!0}}const equalsIndex=token.indexOf("=");if(equalsIndex>=0)return{consumed:1,key:token.slice(2,equalsIndex).trim(),value:token.slice(equalsIndex+1),attached:!0};if(token.startsWith("--no-"))return{consumed:1,key:token.slice(5).trim(),value:!1};const key=token.slice(2).trim(),next=args[index+1];return typeof next=="string"&&!next.startsWith("-")?{consumed:2,key,value:next}:{consumed:1,key,value:!0}}function isUnsafeLooseOptionKey(key){return UNSAFE_LOOSE_OPTION_KEYS.has(key)}function resolveLooseOptionCoercionKind(definition){const raw=(typeof definition.value_type=="string"?definition.value_type:void 0)??(typeof definition.type=="string"?definition.type:void 0);return resolveFlagValueKind(raw)}function collectLooseOptionKeys(definition){const keys=[],long=resolveExtensionLongFlagName(definition.long)??"",short=typeof definition.short=="string"?definition.short.trim():"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}if(short.startsWith("-")&&!short.startsWith("--")){const normalized=toLooseOptionKey(short.slice(1));normalized.length>0&&!isUnsafeLooseOptionKey(normalized)&&keys.push(normalized)}return[...new Set(keys)]}function collectLooseCommandOptionKeysForDefinitions(definitions){const keys=new Set;for(const definition of definitions)for(const key of collectLooseOptionKeys(definition))keys.add(key);return keys}function resolveCanonicalLooseOptionKey(definition){const long=resolveExtensionLongFlagName(definition.long)??"";if(long.startsWith("--")){const normalized=toLooseOptionKey(long.slice(2));if(normalized.length>0&&!isUnsafeLooseOptionKey(normalized))return normalized}return collectLooseOptionKeys(definition)[0]??null}function formatLooseOptionLabel(definition){const long=typeof definition.long=="string"?definition.long.trim():"";if(long.startsWith("--")&&long.length>2)return long;const short=typeof definition.short=="string"?definition.short.trim():"";return short.startsWith("-")&&!short.startsWith("--")&&short.length>1?short:null}function validateLooseCommandOptionsWithFlagDefinitions(options,definitions,commandPath){if(definitions.length===0)return;const allowed=new Set,disabled=new Map,required=[],labels=[];for(const definition of definitions){const keys=collectLooseOptionKeys(definition),normalizedLabel=formatLooseOptionLabel(definition);normalizedLabel!==null&&labels.push(normalizedLabel);for(const key of keys)allowed.add(key),definition.enabled===!1&&disabled.set(key,normalizedLabel);definition.required===!0&&definition.enabled!==!1&&keys.length>0&&required.push({keys,label:normalizedLabel})}for(const key of Object.keys(options)){if(!allowed.has(key)){const expected=labels.length>0?` Expected one of: ${[...new Set(labels)].join(", ")}.`:"";throw new PmCliError(`Unknown option '--${key}' for extension command '${commandPath}'.${expected}`,EXIT_CODE.USAGE)}const disabledLabel=disabled.get(key);if(disabledLabel)throw new PmCliError(`Option '${disabledLabel}' is disabled for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}for(const entry of required)if(!entry.keys.some(key=>Object.hasOwn(options,key)))throw new PmCliError(`Missing required option '${entry.label}' for extension command '${commandPath}'.`,EXIT_CODE.USAGE)}function coerceLooseStringOptionValue(value){return typeof value=="string"||value==null?value:String(value)}function coerceLooseNumberOptionValue(value){if(typeof value=="number")return value;if(typeof value=="string"&&value.trim().length>0){const parsed=Number(value);return Number.isFinite(parsed)?parsed:value}return value}function coerceLooseBooleanOptionValue(value){if(typeof value=="boolean")return value;if(typeof value=="string"){const normalized=value.trim().toLowerCase();if(normalized==="true"||normalized==="1")return!0;if(normalized==="false"||normalized==="0")return!1}return value}const LOOSE_OPTION_VALUE_COERCERS={string:coerceLooseStringOptionValue,number:coerceLooseNumberOptionValue,boolean:coerceLooseBooleanOptionValue};function coerceLooseOptionValue(value,kind){return Array.isArray(value)?value.map(entry=>coerceLooseOptionValue(entry,kind)):LOOSE_OPTION_VALUE_COERCERS[kind](value)}function normalizeAccumulatedFlagValue(value,kind,preserveOccurrenceCommas){const entries=preserveOccurrenceCommas?(Array.isArray(value)?value.flat(1/0):[value]).filter(entry=>entry!=null&&entry!==""):flattenFlagListValue(value);return kind?entries.map(entry=>coerceLooseOptionValue(entry,kind)):entries}function applyFlagDefault(defaultValue,kind,isListFlag,preserveOccurrenceCommas){return isListFlag?normalizeAccumulatedFlagValue(defaultValue,kind,preserveOccurrenceCommas):kind?coerceLooseOptionValue(defaultValue,kind):defaultValue}function readOrderedLooseListValues(occurrenceSource,optionKeys,fallback){const occurrences=occurrenceSource[LOOSE_OPTION_OCCURRENCES];if(!occurrences||occurrences.length===0)return fallback;const acceptedKeys=new Set(optionKeys);return occurrences.filter(occurrence=>acceptedKeys.has(occurrence.key)).map(occurrence=>occurrence.value)}function isBooleanSwitchDefinition(definition){return resolveExtensionFlagValueContract(definition).value_arity==="none"}function refuseStrictScalarValue(definition,kind,entry,expected,commandPath){const label=formatLooseOptionLabel(definition),scope=commandPath?` for extension command '${commandPath}'`:"",received=entry===!0?"no value":JSON.stringify(entry);throw new PmCliError(`Option '${label}'${scope} expects ${expected}; received ${received}.`,EXIT_CODE.USAGE,{code:"extension_flag_value_invalid",required:`Pass ${label} ${kind==="number"?"<number>":"<true|false|1|0>"}.`,why:`The flag declares value_type ${kind} with value_validation strict, so a malformed token is refused before the extension handler runs.`,nextSteps:[`Re-run with a valid ${kind} value for ${label}.`,`Run pm ${commandPath??"<command>"} --help to review the declared flag contract.`]})}function isStrictTypedDefinition(definition,kind){return definition.value_validation==="strict"&&kind!=="string"}function readLooseOccurrences(occurrenceSource,optionKeys){const occurrences=occurrenceSource[LOOSE_OPTION_OCCURRENCES];if(!occurrences)return[];const acceptedKeys=new Set(optionKeys);return occurrences.filter(occurrence=>acceptedKeys.has(occurrence.key))}function refuseMalformedAttachedSwitchValues(definition,optionKeys,occurrenceSource,commandPath){if(isBooleanSwitchDefinition(definition))for(const occurrence of readLooseOccurrences(occurrenceSource,optionKeys)){if(occurrence.attached!==!0)continue;const values=definition.list===!0&&definition.repeatable!==!0?flattenFlagListValue(occurrence.value):[occurrence.value];for(const value of values){const failure=describeFlagScalarValueFailure(coerceLooseOptionValue(value,"boolean"),"boolean");failure!==null&&refuseStrictScalarValue(definition,"boolean",value,failure.expected,commandPath)}}}function refuseEmptyStrictListEntries(definition,kind,rawValue,preserveOccurrenceCommas,commandPath){const occurrences=Array.isArray(rawValue)?rawValue.flat(1/0):[rawValue],entries=preserveOccurrenceCommas?occurrences:occurrences.flatMap(entry=>typeof entry=="string"?entry.split(","):[entry]);for(const entry of entries)if(typeof entry=="string"&&entry.trim().length===0){const failure=describeFlagScalarValueFailure(entry,kind);refuseStrictScalarValue(definition,kind,entry,failure.expected,commandPath)}}function validateStrictScalarOptionValue(definition,value,kind,commandPath){if(!isStrictTypedDefinition(definition,kind))return value;const isSwitch=kind==="boolean"&&isBooleanSwitchDefinition(definition),normalizeEntry=entry=>{const failure=describeFlagScalarValueFailure(entry,kind);return failure===null?entry:isSwitch&&typeof entry=="string"?!0:refuseStrictScalarValue(definition,kind,entry,failure.expected,commandPath)};return Array.isArray(value)?value.map(normalizeEntry):normalizeEntry(value)}function mergeAliasOptionKeys(coerced,canonical,optionKeys,isListFlag){for(const key of optionKeys)if(!(key===canonical||!Object.hasOwn(coerced,key))){if(Object.hasOwn(coerced,canonical)){if(isListFlag){const canonicalValue=coerced[canonical],aliasValue=coerced[key];coerced[canonical]=[...Array.isArray(canonicalValue)?canonicalValue:[canonicalValue],...Array.isArray(aliasValue)?aliasValue:[aliasValue]].filter(value=>value!=null)}delete coerced[key];continue}coerced[canonical]=coerced[key],delete coerced[key]}}function coerceLooseCommandOptionsWithFlagDefinitions(options,definitions,occurrenceSource=options,commandPath){if(definitions.length===0)return options;const coerced=Object.create(null);for(const[key,value]of Object.entries(options))coerced[key]=value;for(const definition of definitions){const canonical=resolveCanonicalLooseOptionKey(definition);canonical&&coerceDefinedLooseOption(coerced,definition,canonical,occurrenceSource,commandPath)}return coerced}function coerceDefinedLooseOption(coerced,definition,canonical,occurrenceSource,commandPath){const isListFlag=definition.list===!0,optionKeys=collectLooseOptionKeys(definition),kind=resolveLooseOptionCoercionKind(definition);kind&&!isListFlag&&refuseMalformedScalarAliasValues(coerced,definition,canonical,optionKeys,kind,commandPath),mergeAliasOptionKeys(coerced,canonical,optionKeys,isListFlag);const preserveOccurrenceCommas=definition.repeatable===!0;if(!Object.hasOwn(coerced,canonical)){definition.default!==void 0&&(coerced[canonical]=applyFlagDefault(definition.default,kind,isListFlag,preserveOccurrenceCommas));return}if(kind==="boolean"&&isStrictTypedDefinition(definition,kind)&&refuseMalformedAttachedSwitchValues(definition,optionKeys,occurrenceSource,commandPath),isListFlag){coerced[canonical]=coerceAccumulatedLooseOption(definition,optionKeys,occurrenceSource,coerced[canonical],kind,preserveOccurrenceCommas,commandPath);return}kind&&(coerced[canonical]=validateStrictScalarOptionValue(definition,coerceLooseOptionValue(coerced[canonical],kind),kind,commandPath))}function refuseMalformedScalarAliasValues(coerced,definition,canonical,optionKeys,kind,commandPath){for(const key of optionKeys)key!==canonical&&Object.hasOwn(coerced,key)&&validateStrictScalarOptionValue(definition,coerceLooseOptionValue(coerced[key],kind),kind,commandPath)}function coerceAccumulatedLooseOption(definition,optionKeys,occurrenceSource,current,kind,preserveOccurrenceCommas,commandPath){const ordered=readOrderedLooseListValues(occurrenceSource,optionKeys,current);kind&&isStrictTypedDefinition(definition,kind)&&refuseEmptyStrictListEntries(definition,kind,ordered,preserveOccurrenceCommas,commandPath);const normalized=normalizeAccumulatedFlagValue(ordered,kind,preserveOccurrenceCommas);return kind?validateStrictScalarOptionValue(definition,normalized,kind,commandPath):normalized}function parseLooseCommandOptions(args){const options=Object.create(null),occurrences=[];Object.defineProperty(options,LOOSE_OPTION_OCCURRENCES,{value:occurrences});let index=0;for(;index<args.length;){const parsed=parseLooseOptionToken(args,index);if(!parsed){index+=1;continue}const normalizedKey=toLooseOptionKey(parsed.key);if(normalizedKey.length===0||isUnsafeLooseOptionKey(normalizedKey)){index+=parsed.consumed;continue}setLooseOptionValue(options,normalizedKey,parsed.value),occurrences.push({...parsed,key:normalizedKey}),index+=parsed.consumed}return options}function collectLoosePositionalArgs(args){const positionals=[];let index=0;for(;index<args.length;){if(args[index]==="--"){positionals.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){index+=Math.max(1,parsed.consumed);continue}positionals.push(args[index]),index+=1}return positionals}function stripLooseCommandOptionTokens(args,definitions){if(definitions.length===0)return[...args];const knownKeys=new Set,booleanKeys=new Set;for(const definition of definitions){const valueKind=resolveLooseOptionCoercionKind(definition);for(const key of collectLooseOptionKeys(definition))knownKeys.add(key),valueKind==="boolean"&&booleanKeys.add(key)}if(knownKeys.size===0)return[...args];const stripped=[];let index=0;for(;index<args.length;){if(args[index]==="--"){stripped.push(...args.slice(index+1));break}const parsed=parseLooseOptionToken(args,index);if(parsed){const normalizedKey=toLooseOptionKey(parsed.key);if(knownKeys.has(normalizedKey)){const token=args[index],consumed=booleanKeys.has(normalizedKey)&&!token.includes("=")?1:parsed.consumed;index+=consumed;continue}}stripped.push(args[index]),index+=1}return stripped}export{coerceLooseCommandOptionsWithFlagDefinitions,collectLooseCommandOptionKeysForDefinitions,collectLoosePositionalArgs,parseLooseCommandOptions,stripLooseCommandOptionTokens,validateLooseCommandOptionsWithFlagDefinitions};
 //# sourceMappingURL=extension-command-options.js.map

package/dist/cli/help-content.js

@@ -1,6 +1,6 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="197ced7a-f930-58a2-9c4e-8dc2cd912784")}catch{}})();import{parseBootstrapHelpRequest}from"./bootstrap-args.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{listPmCommandsForTier,measurePmCoreHelp,PM_CORE_HELP_OPTION_FLAGS,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";import{PM_COMMAND_ALIAS_CONTRACTS,PM_RELOCATED_COMMAND_ALIASES,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts.js";const COMMAND_HELP_VISIBILITY_TIERS=new WeakMap;function setPmCommandHelpVisibilityTier(command,tier){COMMAND_HELP_VISIBILITY_TIERS.set(command,tier)}function getPmCommandHelpVisibilityTier(command){return COMMAND_HELP_VISIBILITY_TIERS.get(command)}function firstExampleOrEmpty(examples){return examples.length>0?[examples[0]]:[]}function renderCompactHelpBundle(bundle){const lines=["","Intent:",`  ${bundle.why}`],compactExamples=firstExampleOrEmpty(bundle.examples);return compactExamples.length>0&&(lines.push("","Example:"),lines.push(`  ${compactExamples[0]}`)),lines.push("","Need deeper rationale and more examples?"),lines.push("  Re-run with --explain."),lines.join(`
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e2469b75-3bde-5b10-ac45-ee71c9a8271e")}catch{}})();import{parseBootstrapHelpRequest}from"./bootstrap-args.js";import{formatPmPositionalActionFlagTip,PM_POSITIONAL_ACTION_CONTRACTS,resolvePmPositionalActionContract}from"../sdk/cli-contracts/grammar-contracts.js";import{listPmCommandsForTier,measurePmCoreHelp,PM_CORE_HELP_OPTION_FLAGS,resolvePmCommandVisibilityTier}from"../sdk/agent-capability-contracts.js";import{PM_COMMAND_ALIAS_CONTRACTS,PM_RELOCATED_COMMAND_ALIASES,renderPmCommandAliasMigrationHint}from"../sdk/cli-contracts.js";const COMMAND_HELP_VISIBILITY_TIERS=new WeakMap;function setPmCommandHelpVisibilityTier(command,tier){COMMAND_HELP_VISIBILITY_TIERS.set(command,tier)}function getPmCommandHelpVisibilityTier(command){return COMMAND_HELP_VISIBILITY_TIERS.get(command)}function firstExampleOrEmpty(examples){return examples.length>0?[examples[0]]:[]}function renderCompactHelpBundle(bundle){const lines=["","Intent:",`  ${bundle.why}`],compactExamples=firstExampleOrEmpty(bundle.examples);return compactExamples.length>0&&(lines.push("","Example:"),lines.push(`  ${compactExamples[0]}`)),lines.push("","Need deeper rationale and more examples?"),lines.push("  Re-run with --explain."),lines.join(`
 `)}function renderDetailedHelpBundle(bundle){const lines=["","Why use this command:",`  ${bundle.why}`,"","Examples:",...bundle.examples.map(example=>`  ${example}`)];return bundle.tips&&bundle.tips.length>0&&(lines.push("","Tips:"),lines.push(...bundle.tips.map(tip=>`  - ${tip}`))),lines.join(`
-`)}function renderHelpBundle(bundle,detailMode){return detailMode==="detailed"?renderDetailedHelpBundle(bundle):renderCompactHelpBundle(bundle)}function normalizeHelpCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}const HELP_PATH_ALIASES={cal:"calendar",ctx:"context"};function findDirectChildCommand(parent,name){return parent.commands.find(entry=>entry.name()===name)??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next)return null;current=next}return current}function attachBundleByPath(root,commandPath,bundle,detailMode){const command=findCommandByPath(root,commandPath.split(" ").filter(part=>part.length>0));command&&command.addHelpText("after",renderHelpBundle(bundle,detailMode))}function resolveHelpDetailMode(argv){return argv.includes("--explain")?"detailed":"compact"}function isFullHelpDiscovery(argv){return argv.includes("--all")||argv.includes("--explain")}const HELP_BY_COMMAND_PATH={"item reopen":{why:"Reopens recurring work while archiving earlier closure evidence and declaring its current planning outcome.",examples:['pm item reopen pm-a1b2 "The failure recurred" --expected-result "The recurrence regression passes"'],tips:["Without --expected-result, follow recovery.suggested_retry_args to restore current planning before claiming the item."]},ops:{why:"Groups workspace diagnostics, quality checks, and maintenance under one discoverable command.",examples:["pm ops health --summary","pm ops validate --check-history-drift","pm ops --help"]},init:{why:"Bootstraps tracker storage and settings so all other commands can run safely.",examples:["pm init","pm init acme","pm init ./pm-sandbox --defaults","pm init --preset minimal","pm init --agent-guidance add","pm init --defaults --with-packages"],tips:["Run this once per repository before create/list/update commands.","A path-like positional (`./dir`, `/tmp/dir`) initializes that tracker path; a plain word remains an id prefix.","Rewriting id prefix, governance preset, or default author on an existing tracker requires --force.","Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.","Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.","Use --with-packages when agents need bundled commands such as calendar and templates available immediately."]},config:{why:"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.",examples:["pm config project get definition-of-done",'pm config project set definition-of-done --criterion "tests pass"',"pm config project set item-format --format toon","pm config project set sprint-release-format-policy --policy strict_error","pm config project set governance-preset --policy minimal","pm config project set governance-ownership-enforcement --policy none","pm config project set test-result-tracking --policy enabled","pm config global set telemetry-tracking --policy disabled"]},extension:{why:"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.",examples:["pm install ./my-package --project","pm install '*' --project","pm package doctor --project --detail summary","pm package manage --global","pm package activate sample-ext --project","pm package deactivate sample-ext --project","pm package uninstall sample-ext --global","pm extension explore --project","pm extension manage --global","pm extension describe sample-ext --project","pm extension doctor --detail deep"],tips:["Prefer pm install and pm package in new user-facing automation.","Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.","Bundled aliases beads and todos resolve to package-shipped extension sources.","Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.","Install updates settings activation state automatically unless extension allowlist mode is unchanged.","Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.","Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.","Use --describe to map exactly what each loaded extension registers (commands, hooks, item types, providers, overrides) in one call.","Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads."]},package:{why:"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.",examples:["pm install npm:@scope/pm-package --project","pm package install ./my-package --project","pm package doctor --project --detail deep","pm package manage --project --runtime-probe","pm package describe --project","pm package activate sample-ext --project","pm upgrade --packages-only --dry-run"],tips:["Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.","Use pm package describe [name] to map every surface a package registers without reading its manifest or running diagnostics.","Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.","Use --dry-run before upgrade when automation needs a deterministic plan."]},"package init":{why:"Generates an installable starter pm package with package metadata and a root extension entrypoint.",examples:["pm package init ./my-package","pm package init ./my-hook-package --capability hooks","pm package init ./my-search-package --capability search","pm package init ./my-sync-package --capability importers","pm package init ./my-domain-package --capability schema","pm package init ./my-output-package --capability renderers","pm install ./my-sync-package --project","pm package doctor --project --detail summary"],tips:["Use --capability hooks for a starter after_command lifecycle reactor with runnable SDK testing coverage.","Use --capability search for a starter search provider/vector-store adapter with runnable SDK testing coverage.","Use --capability importers for paired import/export commands that move project context across systems.","Use --capability schema for a starter custom item type, field, and migration so pm models your project domain.","Use --capability renderers/parser/preflight/services for starter override surfaces (output renderer, parsed-option rewrite, pre-run gate decision, built-in service) \u2014 one runnable starter per SDK capability.","The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.","Use package doctor after changes to verify activation, policy, and collision diagnostics."]},"package install":{why:"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.",examples:["pm package install ./my-package --project","pm install npm:pm-changelog --project","pm package install --github org/repo/packages/my-pm-package --ref main"],tips:["Prefer the top-level pm install alias in scripts when only installation is needed.","Run pm package manage or pm package doctor after installing external packages."]},"package doctor":{why:"Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.",examples:["pm package doctor --project --detail summary","pm package doctor --project --detail deep --trace","pm package doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed package registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global package state: PM_GLOBAL_PATH=$(mktemp -d) pm package doctor --project --detail deep --trace.","Non-isolated project diagnostics include global registrations and emit remediation when global package state can affect the result."]},"package catalog":{why:"Lists bundled first-party package catalog metadata and compact field projections.",examples:["pm package catalog --project","pm package catalog --project --fields alias,installed,install_command","pm package list --project --fields alias,package_name,category"],tips:["Use --fields for low-token package discovery in agent loops.","External npm package discovery still belongs to npm search."]},"extension init":{why:"Generates an installable starter runtime extension with manifest and entrypoint files.",examples:["pm extension init ./my-extension","pm extension init ./my-hook-extension --capability hooks","pm extension init ./my-search-extension --capability search","pm extension init ./my-sync-extension --capability importers","pm extension init ./my-domain-extension --capability schema","pm extension init ./my-output-extension --capability renderers","pm extension --install --project ./my-sync-extension","pm extension --doctor --project --detail summary"],tips:["Use --capability hooks when the extension should react to command lifecycle events.","Use --capability search when the extension should register retrieval primitives.","Use --capability importers when the extension should register project-context import/export commands.","Use --capability schema when the extension should register custom item types, fields, and migrations.","Use --capability renderers/parser/preflight/services to override pm's output rendering, parsed options, pre-run gate, or a built-in service.","Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold."]},"extension install":{why:"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.",examples:["pm extension install ./my-extension --project","pm extension --install --project ./my-extension","pm extension doctor --project --detail summary"],tips:["Prefer pm install or pm package install for new package-first automation."]},"extension doctor":{why:"Diagnoses compatibility extension activation, policy, collision, and managed-state health for project or global extension scopes.",examples:["pm extension doctor --project --detail summary","pm extension doctor --project --detail deep --trace","pm extension doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed extension registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global extension state: PM_GLOBAL_PATH=$(mktemp -d) pm extension doctor --project --detail deep --trace.","Prefer pm package doctor in new package-first workflows."]},"extension catalog":{why:"Compatibility view of bundled package catalog metadata.",examples:["pm extension catalog --project","pm extension catalog --project --fields alias,installed,install_command"],tips:["Prefer pm package catalog in new user-facing workflows."]},install:{why:"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",examples:["pm install '*' --project","pm install ./packages/pm-todos --project","pm install npm:@scope/pm-package --global","pm install --github org/repo/packages/my-pm-package --ref main"],tips:["Installed packages are recorded in managed state and can be inspected with pm package manage."]},upgrade:{why:"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.",examples:["pm upgrade --dry-run","pm upgrade --packages-only --project","pm upgrade todos --dry-run","pm upgrade --cli-only --repair","pm upgrade --tag next --dry-run"],tips:["Omit target to include the CLI/SDK plus all managed packages in the selected scope.","Pass a target to refresh one managed package by name, directory, package name, or source.","Use --packages-only in repository automation when the global CLI should not be changed."]},create:{why:"Creates a new planning item with deterministic metadata and history.",examples:['pm create --title "Harden lock flow" --description "Improve stale lock handling" --type Task --status open --priority 1 --message "Create lock hardening task" --create-mode progressive','pm create --title "Weekly planning sync" --description "Recurring coordination meeting" --type Meeting --schedule-preset lightweight','pm create --title "Asset: Hero model" --description "Track playable model asset" --type Asset --status open --priority 1 --message "Create asset item" --type-option category=Character --dep "id=pm-epic01,kind=parent,created_at=now" --comment "created_at=now,text=Why this asset item exists." --note "created_at=now,text=Initial implementation note." --learning "created_at=now,text=Durable lesson placeholder." --file "path=src/assets/hero.glb,note=tracked asset" --test "command=node scripts/run-tests.mjs test,timeout_seconds=240" --doc "path=README.md,note=asset docs"'],tips:["Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.","Use --type <value> to load type-aware policy guidance in --help output."]},focus:{why:"Sets a session focused item so new pm create items default their --parent to it (project management = context management).",examples:["pm focus pm-epic1","pm focus","pm focus --clear"],tips:["Focus is session-local (stored in .agents/pm/runtime/session.json, gitignored) \u2014 it never affects teammates.",'An explicit --parent on pm create always overrides the focused item; use --parent "" to create with no parent.',"A stale focused item produces the same missing-parent validation as an explicit stale --parent."]},update:{why:"Mutates existing item fields while preserving history and lock safety.",examples:['pm update pm-a1b2 --status in_progress --message "Start implementation"','pm update pm-a1b2 --unset close-reason --message "Clear stale close reason after reopen"','pm update pm-a1b2 --unset assignee --deadline +2d --message "Replan ownership and deadline"','pm update pm-a1b2 --body "Backfilled body text for legacy item" --message "Normalize missing body"'],tips:['Use "pm close <ID> <TEXT>" to close items instead of --status closed.',"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.",'Use "pm append <ID> --body <text>" for additive notes; use update --body to replace body content.']},"update-many":{why:"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.",examples:["pm update-many --filter-status open --status in_progress --dry-run",'pm update-many --filter-tag wave:7 --replace-tests --test "command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240"','pm update-many --filter-tag governance --reviewer maintainer-review --message "Normalize reviewer metadata"',"pm update-many --rollback ckpt-abc123"],tips:["Use --dry-run first to inspect proposed changes before apply mode.","Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).","Checkpoints are enabled by default for apply mode and can be restored with --rollback."]},"close-many":{why:"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints \u2014 unlike update-many --status closed, which bypasses close validation.",examples:['pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run','pm close-many --filter-tag wave:7 --reason "Superseded by redesign" --validate-close warn','pm close-many --ids pm-a,pm-b,pm-c --reason "Closed in batch" --resolution "Verified by integration suite"',"pm close-many --rollback close-many-20260604-abc123"],tips:["At least one filter (--filter-* or --ids) is required so close-many never matches every item.","Already-terminal matches are skipped by default; pass --force to re-close them.","Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.","Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>."]},templates:{why:"Saves, lists, and inspects reusable create option bundles for repeatable workflows.",examples:['pm templates save triage-default --title "Triage item" --description "..." --type Task --status open --priority 2 --message "Seed triage template"',"pm templates list","pm templates show triage-default"],tips:["Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.","Combine templates with explicit create flags; explicit flags always override template defaults."]},deps:{why:"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.",examples:["pm deps pm-a1b2","pm deps pm-a1b2 --format graph","pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary"],tips:["Use --summary for lightweight counts when full graph payloads are unnecessary."]},list:{why:"Lists active items with deterministic filtering and ordering.",examples:["pm list --limit 20","pm list --type Task --priority 0 --tag release --status in_progress","pm list --compact --sort deadline --order asc","pm list --fields id,title,parent,type --sort parent --order asc"]},"list-all":{why:"Lists all item states (including terminal states) when you need full visibility.",examples:["pm list-all --limit 50","pm list-all --type Issue --include-body"]},"list-open":{why:"Shows work that is ready to claim and start.",examples:["pm list-open --priority 0 --limit 10"]},"list-in-progress":{why:"Tracks active execution and owner progress.",examples:["pm list-in-progress --priority 0 --limit 20"]},"list-blocked":{why:"Surfaces blocked work that needs intervention.",examples:["pm list-blocked --limit 20"]},"list-closed":{why:"Reviews completed work and closure outcomes.",examples:["pm list-closed --limit 20 --type Task"]},"list-canceled":{why:"Audits intentionally discontinued work.",examples:["pm list-canceled --limit 20"]},"list-draft":{why:"Finds incompletely defined items that need refinement before execution.",examples:["pm list-draft --limit 20"]},aggregate:{why:"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.",examples:["pm aggregate --group-by parent,type --count","pm aggregate --group-by type,status --count","pm aggregate --group-by parent,type --count --status open --parent pm-feature01"],tips:["Current aggregate mode is grouped counts only, so pass --count explicitly."]},guide:{why:"Routes local progressive-disclosure documentation so agents can fetch only the context they need.",examples:["pm install guide-shell --project","pm guide","pm guide quickstart","pm guide commands --depth standard","pm guide skills --depth deep --format markdown","pm guide release --json"],tips:["Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.","Use --list to force topic index output even when topic parsing is ambiguous."]},calendar:{why:"Provides deadline/reminder/event scheduling views for planning and coordination.",examples:["pm calendar","pm calendar --view agenda --from +0d --to +7d --tag release","pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events","pm calendar --view month --tag release --format json"],tips:["Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.","--full-period applies only to day/week/month views; use --from/--to to bound agenda windows."]},context:{why:"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.",examples:["pm context","pm ctx --depth standard --limit 10","pm ctx --depth deep --tag release","pm ctx --section hierarchy --section progress --section blockers","pm context --depth standard --activity-limit 20 --stale-threshold 14d","pm context --from +0d --to +7d --format markdown --depth deep"],tips:["High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.","When no open or in-progress work exists, blocked items are shown as fallback context.","--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.","--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.","Configure defaults via pm config project set context --default-depth standard --activity-limit 15."]},next:{why:"Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.",examples:["pm next","pm next --json","pm next --limit 3 --ready-only","pm next --parent pm-mpbb","pm next --tag release --format markdown"],tips:["Ready = active status, no open blockers, and no open children (a concrete leaf); the recommendation resumes in-progress work before starting new work.","An item is blocked when its scalar blocked_by or a blocked_by dependency points at a non-terminal item; the blocked list names the blockers to clear.","Containers (Epics/Features with open children) are never recommended directly \u2014 the actionable leaf beneath them is.","Use --parent to scope to one epic's subtree, or --ready-only to drop the blocked companion list for the tightest output."]},search:{why:"Finds relevant items by keyword, semantic, or hybrid retrieval modes.",examples:['pm search "lock stale retry" --mode keyword --limit 10','pm search "extension migration blockers" --mode hybrid --type Task --priority 0','pm search "Cross-Epic Realism Dependency Council" --mode keyword --title-exact'],tips:["Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.","Use --include-linked when linked docs/files/tests should influence scoring."]},eval:{why:"Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.",examples:["pm eval --json","pm eval --mode hybrid --k 10","pm eval --fail-under 0.6 --json","pm eval --queries ./my-eval.json --mode semantic"],tips:["Curate ground truth in <pmRoot>/search/eval-queries.json as an array of {query, relevant_ids, mode?} objects.","Wire --fail-under into CI to fail the build when aggregate nDCG@k drops below your baseline."]},reindex:{why:"Rebuilds search artifacts after large changes to item corpus or provider/vector config.",examples:["pm reindex --mode keyword","pm reindex --mode hybrid --progress --json"],tips:["Use --progress for non-interactive visibility during local embedding runs.","JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr."]},get:{why:"Shows details for one item by ID, with optional lower-token projections for agent loops.",examples:["pm get pm-a1b2","pm get pm-a1b2 --depth brief --json","pm get pm-a1b2 --fields id,title,status,parent,type --json","pm get pm-a1b2 --at 7 --fields id,title,status,body --json"],tips:["Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.","Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.","Schedule metadata is normalized under schedule; request schedule.start_at or schedule.location for narrow calendar reads.","Children are type-agnostic and include bounded deterministic samples plus continuation metadata when a parent has direct children.","Use --at <version|timestamp> for a verified read-only historical projection; reconstructed/as_of fields distinguish it from current state.","JSON output shape is { item, linked, claim_state, schedule, children }; body is nested at item.body (parity with list --include-body)."]},history:{why:"Inspects item mutation timeline and audit trail.",examples:["pm history pm-a1b2 --limit 20","pm history pm-a1b2 --full --verify"]},"history-compact":{why:"Compacts long history streams into a synthetic checkpoint while preserving replay integrity. Pass an item id for one stream, or a bulk selector (--ids/--all-over/--closed/--all-streams) to sweep many.",examples:["pm history-compact pm-a1b2 --dry-run",'pm history-compact pm-a1b2 --before 25 --message "Compact early history"',"pm history-compact --all-over 500 --dry-run","pm history-compact --closed","pm history-compact --ids pm-a1b2,pm-c3d4 --dry-run"]},activity:{why:"Reviews recent tracker-wide activity across items.",examples:["pm activity --limit 50","pm activity --full --id pm-a1b2 --limit 50","pm activity --id pm-a1b2 --op update --from -7d --to now","pm activity --json --stream rows --limit 200"],tips:["Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive."]},restore:{why:"Restores an item to a prior timestamp/version with history replay safety.",examples:['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --message "Rollback to known-good state"']},close:{why:"Transitions work to terminal closed state with explicit rationale.",examples:['pm close pm-a1b2 "Done" --release-assignment --validate-close warn','pm close pm-a1b2 "Done" --validate-close','pm close pm-a1b2 "Done" --validate-close off','pm close pm-a1b2 "Done" --validate-close strict']},delete:{why:"Removes an item while preserving history evidence and lock/ownership checks.",examples:['pm delete pm-a1b2 --message "Remove duplicate item"']},append:{why:"Adds implementation notes to body without replacing existing content.",examples:['pm append pm-a1b2 --body "Implemented retry with bounded backoff." --message "Record implementation detail"']},comments:{why:"Adds or reviews lightweight status updates linked to an item.",examples:['pm comments pm-a1b2 "Verified fix on Linux and macOS"','pm comments pm-a1b2 --add "Verified fix on Linux and macOS"','printf "%s\\n" "## Verification" "- linux pass" "- mac pass" | pm comments pm-a1b2 --stdin',"pm comments pm-a1b2 --file docs/release-evidence.md",'pm comments pm-a1b2 --add "text: verification note with commas, key-like words, and parser details"','pm comments pm-a1b2 --add "Follow-up needed after review" --force',"pm comments pm-a1b2 --limit 10"],tips:["Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.","Use --force when adding comments to items currently assigned to a different owner.","When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent."]},notes:{why:"Adds or reviews durable implementation notes linked to an item.",examples:['pm notes pm-a1b2 --add "Investigated parser edge case and documented fallback logic."','pm notes pm-a1b2 --add "text: parser rationale with commas, colons, and key-like wording"','pm notes pm-a1b2 --edit 1 --add "Corrected durable note"',"pm notes pm-a1b2 --delete 2","pm notes pm-a1b2 --limit 10"],tips:["CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required."]},learnings:{why:"Adds or reviews post-implementation learnings for future work.",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 --delete 2","pm learnings pm-a1b2 --limit 10"],tips:["If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text."]},files:{why:"Associates changed source files with tracker items for reproducibility.",examples:['pm files pm-a1b2 --add "path=src/cli/main.ts,note=help orchestration"','pm files pm-a1b2 --add src/cli/main.ts --note "help orchestration"',"pm files discover pm-a1b2",'pm files discover pm-a1b2 --apply --note "discovered from item text"']},docs:{why:"Associates relevant documentation paths with tracker items.",examples:['pm docs pm-a1b2 --add "path=README.md,note=user-facing command guidance"','pm docs pm-a1b2 --add README.md --note "user-facing command guidance"']},test:{why:"Links test commands/paths and optionally executes them for one item.",examples:['pm test pm-a1b2 --add "command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\s+\\d+"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,pm_context_mode=auto"',"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped","pm test pm-a1b2 --run --timeout 2400 --pm-context auto","pm test pm-a1b2 --run --background --timeout 2400 --progress"]},"test-all":{why:"Runs linked tests in bulk for release/readiness sweeps.",examples:["pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400","pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped","pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm","pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch","pm test-all --status in_progress --background --timeout 3600"]},"test-runs":{why:"Manages background linked-test runs with lifecycle controls and log/status inspection.",examples:["pm test-runs list --status running --limit 20","pm test-runs status tr-abc123","pm test-runs logs tr-abc123 --stream stderr --tail 200","pm test-runs stop tr-abc123","pm test-runs resume tr-abc123"]},stats:{why:"Reports tracker-level totals and distribution by type/status.",examples:["pm stats","pm stats --json"]},telemetry:{why:"Inspects and manages local telemetry queue/runtime state for observability diagnostics.",examples:["pm telemetry status","pm telemetry stats --limit 10","pm telemetry flush","pm telemetry clear"]},health:{why:"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.",examples:["pm health","pm health --check-only --summary --json","pm health --brief --json","pm health --no-refresh","pm health --refresh-vectors"]},validate:{why:"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.",examples:["pm validate","pm validate --check-resolution --json","pm validate --check-lifecycle --dependency-cycle-severity error","pm validate --check-lifecycle --parent-cycle-severity error","pm validate --check-files --scan-mode tracked-all","pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals","pm validate --check-command-references","pm validate --check-resolution --fail-on-warn --json"],tips:["Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details."]},gc:{why:"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.",examples:["pm gc --dry-run","pm gc"]},claim:{why:"Claims an item to signal active ownership and reduce conflicts.",examples:["pm claim pm-a1b2 --start",'pm claim pm-a1b2 --force --message "Take over terminal item"','pm claim pm-a1b2 --author "release-service" --message "Explicit non-agent identity override"'],tips:["Claim takeover for non-terminal items does not require --force; --force is reserved for terminal/lock overrides.","Harness identity is automatic; use --author only to assert an intentional external principal."]},release:{why:"Releases an active claim when paused, handed off, or completed.",examples:["pm release pm-a1b2 --pause"]},"start-task":{why:"Lifecycle alias that claims an item and sets status to in_progress.",examples:['pm start-task pm-a1b2 --message "Start implementation"']},"pause-task":{why:"Lifecycle alias that sets status to open and releases active assignment.",examples:['pm pause-task pm-a1b2 --message "Pause for dependency unblock"']},"close-task":{why:"Lifecycle alias that closes with reason text and clears assignment metadata.",examples:['pm close-task pm-a1b2 "All acceptance criteria met" --message "Close and handoff"']},meet:{why:"Shortcut to create a Meeting from friendly time flags (start/duration) without structured --event CSV.",examples:['pm meet "Sprint Planning" --start +1h --duration 1h','pm meet "1:1" --start 2026-07-01T15:00:00Z --end 2026-07-01T15:30:00Z --location "Room A"'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},event:{why:"Shortcut to create an Event from friendly time flags (start/duration) without structured --event CSV.",examples:['pm event "Release v2" --start 2026-07-01T10:00:00Z --duration 2h','pm event "Conference" --start 2026-08-01 --all-day'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},remind:{why:"Shortcut to create a Reminder from a single point in time without structured --reminder CSV.",examples:['pm remind "Review PR" --at +2d','pm remind "Follow up" --at 2026-07-01T09:00:00Z --text "Ping the team"'],tips:["The reminder time defaults to +1d and the reminder text defaults to the title."]},completion:{why:"Generates shell completion scripts for faster and more reliable command entry.",examples:["pm completion bash","pm completion zsh","pm completion fish","pm completion bash --eager-tags"],tips:["Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly."]},contracts:{why:"Exposes machine-readable CLI command and tool schema contracts for agent integrations.",examples:["pm contracts","pm contracts --command list --runtime-only","pm contracts --command update --flags-only","pm contracts --availability-only --runtime-only","pm contracts --action create","pm contracts --schema-only"],tips:["Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads."]}};for(const{alias,canonical}of PM_RELOCATED_COMMAND_ALIASES){const bundle=HELP_BY_COMMAND_PATH[alias];bundle&&(HELP_BY_COMMAND_PATH[canonical]={...bundle,examples:bundle.examples.map(example=>example.replace(`pm ${alias}`,`pm ${canonical}`))})}const ROOT_HELP_BUNDLE={why:"Provides deterministic project management workflows for humans and coding agents.",examples:["pm init","pm install guide-shell --project","pm list-open --limit 10",'pm create --title "..." --description "..." --type Task --status open --priority 1 --message "..." --create-mode progressive'],tips:["Use <command> --help for command-specific guidance and examples.","Install guide-shell before using pm guide for local docs and skills routing.","Use --json for machine parsing and integration flows.","Use --no-pager to force direct help output in CI and other non-interactive shells."]},deprecatedHelpAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(entry=>entry.lifecycle==="deprecated");for(const contract of deprecatedHelpAliases){const bundle=HELP_BY_COMMAND_PATH[contract.alias];HELP_BY_COMMAND_PATH[contract.alias]={...bundle,why:`Deprecated: use pm ${contract.canonical_argv.join(" ")}. ${bundle.why}`}}for(const bundle of[ROOT_HELP_BUNDLE,...Object.values(HELP_BY_COMMAND_PATH)])bundle.examples=bundle.examples.map(example=>{for(const contract of deprecatedHelpAliases){const alias=contract.alias.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");example=example.replaceAll(new RegExp(`\\bpm ${alias}(?![\\w-])`,"g"),`pm ${contract.canonical_argv.join(" ")}`)}return example});function resolveCanonicalHelpPath(commandPath){const normalized=normalizeHelpCommandPath(commandPath??"");return normalized?HELP_PATH_ALIASES[normalized]??normalized:""}function resolveHelpBundleForPath(commandPath){const canonicalPath=resolveCanonicalHelpPath(commandPath);return canonicalPath?HELP_BY_COMMAND_PATH[canonicalPath]??ROOT_HELP_BUNDLE:ROOT_HELP_BUNDLE}function resolveHelpNarrative(commandPath,detailMode){const bundle=resolveHelpBundleForPath(commandPath);return{intent:bundle.why,examples:detailMode==="detailed"?[...bundle.examples]:firstExampleOrEmpty(bundle.examples),tips:detailMode==="detailed"?[...bundle.tips??[]]:[],detail_mode:detailMode}}function renderFullCommandAliasHelp(){const permanentAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="permanent"),deprecatedAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="deprecated");return["","Command aliases:",...permanentAliases.map(({alias,canonical_argv:canonicalArgv})=>`  ${alias} -> pm ${canonicalArgv.join(" ")}`),"","Deprecated aliases:",...deprecatedAliases.map(contract=>`  ${contract.alias} -> pm ${contract.canonical_argv.join(" ")} (${renderPmCommandAliasMigrationHint(contract)})`)].join(`
+`)}function renderHelpBundle(bundle,detailMode){return detailMode==="detailed"?renderDetailedHelpBundle(bundle):renderCompactHelpBundle(bundle)}function normalizeHelpCommandPath(commandPath){return commandPath.trim().toLowerCase().split(/\s+/).filter(part=>part.length>0).join(" ")}const HELP_PATH_ALIASES={cal:"calendar",ctx:"context"};function findDirectChildCommand(parent,name){return parent.commands.find(entry=>entry.name()===name)??null}function findCommandByPath(root,pathParts){let current=root;for(const part of pathParts){const next=findDirectChildCommand(current,part);if(!next)return null;current=next}return current}function attachBundleByPath(root,commandPath,bundle,detailMode){const command=findCommandByPath(root,commandPath.split(" ").filter(part=>part.length>0));command&&command.addHelpText("after",renderHelpBundle(bundle,detailMode))}function resolveHelpDetailMode(argv){return argv.includes("--explain")?"detailed":"compact"}function isFullHelpDiscovery(argv){return argv.includes("--all")||argv.includes("--explain")}const HELP_BY_COMMAND_PATH={"item reopen":{why:"Reopens recurring work while archiving earlier closure evidence and declaring its current planning outcome.",examples:['pm item reopen pm-a1b2 "The failure recurred" --expected-result "The recurrence regression passes"'],tips:["Without --expected-result, follow recovery.suggested_retry_args to restore current planning before claiming the item."]},ops:{why:"Groups workspace diagnostics, quality checks, and maintenance under one discoverable command.",examples:["pm ops health --summary","pm ops validate --check-history-drift","pm ops --help"]},init:{why:"Bootstraps tracker storage and settings so all other commands can run safely.",examples:["pm init","pm init acme","pm init ./pm-sandbox --defaults","pm init --preset minimal","pm init --agent-guidance add","pm init --defaults --with-packages"],tips:["Run this once per repository before create/list/update commands.","A path-like positional (`./dir`, `/tmp/dir`) initializes that tracker path; a plain word remains an id prefix.","Rewriting id prefix, governance preset, or default author on an existing tracker requires --force.","Use --preset for non-interactive automation; omit it in a TTY to use the setup wizard.","Use --agent-guidance add to inject compact AGENTS/CLAUDE workflow guidance, or --agent-guidance status to inspect missing guidance without modifying files.","Use --with-packages when agents need bundled commands such as calendar and templates available immediately."]},config:{why:"Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.",examples:["pm config project get definition-of-done",'pm config project set definition-of-done --criterion "tests pass"',"pm config project set item-format --format toon","pm config project set sprint-release-format-policy --policy strict_error","pm config project set governance-preset --policy minimal","pm config project set governance-ownership-enforcement --policy none","pm config project set test-result-tracking --policy enabled","pm config global set telemetry-tracking --policy disabled"]},extension:{why:"Compatibility command for package-backed runtime extension lifecycle operations across project or global scope.",examples:["pm install ./my-package --project","pm install '*' --project","pm package doctor --project --detail summary","pm package manage --global","pm package activate sample-ext --project","pm package deactivate sample-ext --project","pm package uninstall sample-ext --global","pm extension explore --project","pm extension manage --global","pm extension describe sample-ext --project","pm extension doctor --detail deep"],tips:["Prefer pm install and pm package in new user-facing automation.","Use pm extension when maintaining existing extension-specific scripts or debugging the compatibility runtime directly.","Bundled aliases beads and todos resolve to package-shipped extension sources.","Use --gh/--github shorthand for GitHub sources and --ref to pin a branch, tag, or ref.","Install updates settings activation state automatically unless extension allowlist mode is unchanged.","Use --adopt for single-extension adoption and --adopt-all to bulk-register unmanaged installs as managed without reinstalling.","Use --manage for concise triage summaries and remediation-oriented diagnostics alongside full extension details.","Use --describe to map exactly what each loaded extension registers (commands, hooks, item types, providers, overrides) in one call.","Use --doctor for consolidated diagnostics with warning codes, remediation hints, and optional deep detail payloads."]},package:{why:"Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.",examples:["pm install npm:@scope/pm-package --project","pm package install ./my-package --project","pm package doctor --project --detail deep","pm package manage --project --runtime-probe","pm package describe --project","pm package activate sample-ext --project","pm upgrade --packages-only --dry-run"],tips:["Prefer package vocabulary for user-facing workflows; extension vocabulary remains available for compatibility.","Use pm package describe [name] to map every surface a package registers without reading its manifest or running diagnostics.","Use pm upgrade to refresh the CLI/SDK and managed packages from their recorded sources.","Use --dry-run before upgrade when automation needs a deterministic plan."]},"package init":{why:"Generates an installable starter pm package with package metadata and a root extension entrypoint.",examples:["pm package init ./my-package","pm package init ./my-hook-package --capability hooks","pm package init ./my-search-package --capability search","pm package init ./my-sync-package --capability importers","pm package init ./my-domain-package --capability schema","pm package init ./my-output-package --capability renderers","pm install ./my-sync-package --project","pm package doctor --project --detail summary"],tips:["Use --capability hooks for a starter after_command lifecycle reactor with runnable SDK testing coverage.","Use --capability search for a starter search provider/vector-store adapter with runnable SDK testing coverage.","Use --capability importers for paired import/export commands that move project context across systems.","Use --capability schema for a starter custom item type, field, and migration so pm models your project domain.","Use --capability renderers/parser/preflight/services for starter override surfaces (output renderer, parsed-option rewrite, pre-run gate decision, built-in service) \u2014 one runnable starter per SDK capability.","The generated package is local-install safe; add SDK runtime imports only after declaring dependencies and validating with package doctor.","Use package doctor after changes to verify activation, policy, and collision diagnostics."]},"package install":{why:"Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.",examples:["pm package install ./my-package --project","pm install npm:pm-changelog --project","pm package install --github org/repo/packages/my-pm-package --ref main"],tips:["Prefer the top-level pm install alias in scripts when only installation is needed.","Run pm package manage or pm package doctor after installing external packages."]},"package doctor":{why:"Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.",examples:["pm package doctor --project --detail summary","pm package doctor --project --detail deep --trace","pm package doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed package registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global package state: PM_GLOBAL_PATH=$(mktemp -d) pm package doctor --project --detail deep --trace.","Non-isolated project diagnostics include global registrations and emit remediation when global package state can affect the result."]},"package catalog":{why:"Lists bundled first-party package catalog metadata and compact field projections.",examples:["pm package catalog --project","pm package catalog --project --fields alias,installed,install_command","pm package list --project --fields alias,package_name,category"],tips:["Use --fields for low-token package discovery in agent loops.","External npm package discovery still belongs to npm search."]},"extension init":{why:"Generates an installable starter runtime extension with manifest and entrypoint files.",examples:["pm extension init ./my-extension","pm extension init ./my-hook-extension --capability hooks","pm extension init ./my-search-extension --capability search","pm extension init ./my-sync-extension --capability importers","pm extension init ./my-domain-extension --capability schema","pm extension init ./my-output-extension --capability renderers","pm extension --install --project ./my-sync-extension","pm extension --doctor --project --detail summary"],tips:["Use --capability hooks when the extension should react to command lifecycle events.","Use --capability search when the extension should register retrieval primitives.","Use --capability importers when the extension should register project-context import/export commands.","Use --capability schema when the extension should register custom item types, fields, and migrations.","Use --capability renderers/parser/preflight/services to override pm's output rendering, parsed options, pre-run gate, or a built-in service.","Use package init for new distributable package workflows; extension init is the compatibility-level runtime scaffold."]},"extension install":{why:"Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.",examples:["pm extension install ./my-extension --project","pm extension --install --project ./my-extension","pm extension doctor --project --detail summary"],tips:["Prefer pm install or pm package install for new package-first automation."]},"extension doctor":{why:"Diagnoses compatibility extension activation, policy, collision, and managed-state health for project or global extension scopes.",examples:["pm extension doctor --project --detail summary","pm extension doctor --project --detail deep --trace","pm extension doctor --project --isolated --detail deep --trace"],tips:["Use --isolated (alias --ignore-global) for hermetic project smoke tests that must ignore globally installed extension registrations.","Set PM_GLOBAL_PATH for a whole subprocess suite when every pm invocation must avoid machine-local global extension state: PM_GLOBAL_PATH=$(mktemp -d) pm extension doctor --project --detail deep --trace.","Prefer pm package doctor in new package-first workflows."]},"extension catalog":{why:"Compatibility view of bundled package catalog metadata.",examples:["pm extension catalog --project","pm extension catalog --project --fields alias,installed,install_command"],tips:["Prefer pm package catalog in new user-facing workflows."]},install:{why:"Installs a pm package into project scope by default, using local, npm, GitHub, or bundled alias sources.",examples:["pm install '*' --project","pm install ./packages/pm-todos --project","pm install npm:@scope/pm-package --global","pm install --github org/repo/packages/my-pm-package --ref main"],tips:["Installed packages are recorded in managed state and can be inspected with pm package manage."]},upgrade:{why:"Updates the global pm CLI/SDK and refreshes managed pm packages from recorded install sources.",examples:["pm upgrade --dry-run","pm upgrade --packages-only --project","pm upgrade todos --dry-run","pm upgrade --cli-only --repair","pm upgrade --tag next --dry-run"],tips:["Omit target to include the CLI/SDK plus all managed packages in the selected scope.","Pass a target to refresh one managed package by name, directory, package name, or source.","Use --packages-only in repository automation when the global CLI should not be changed."]},create:{why:"Creates a new planning item with deterministic metadata and history.",examples:['pm create --title "Harden lock flow" --description "Improve stale lock handling" --type Task --status open --priority 1 --message "Create lock hardening task" --create-mode progressive','pm create --title "Weekly planning sync" --description "Recurring coordination meeting" --type Meeting --schedule-preset lightweight','pm create --title "Asset: Hero model" --description "Track playable model asset" --type Asset --status open --priority 1 --message "Create asset item" --type-option category=Character --dep "id=pm-epic01,kind=parent,created_at=now" --comment "created_at=now,text=Why this asset item exists." --note "created_at=now,text=Initial implementation note." --learning "created_at=now,text=Durable lesson placeholder." --file "path=src/assets/hero.glb,note=tracked asset" --test "command=node scripts/run-tests.mjs test,timeout_seconds=240" --doc "path=README.md,note=asset docs"'],tips:["Use --schedule-preset lightweight for Reminder/Meeting/Event when you want minimal required create inputs.","Use --type <value> to load type-aware policy guidance in --help output.","Bulk creation is pm item mutate --from items.jsonl (JSON Lines, array, or envelope; --upsert-key <field> makes re-runs idempotent)."]},focus:{why:"Sets a session focused item so new pm create items default their --parent to it (project management = context management).",examples:["pm focus pm-epic1","pm focus","pm focus --clear"],tips:["Focus is session-local (stored in .agents/pm/runtime/session.json, gitignored) \u2014 it never affects teammates.",'An explicit --parent on pm create always overrides the focused item; use --parent "" to create with no parent.',"A stale focused item produces the same missing-parent validation as an explicit stale --parent."]},update:{why:"Mutates existing item fields while preserving history and lock safety.",examples:['pm update pm-a1b2 --status in_progress --message "Start implementation"','pm update pm-a1b2 --unset close-reason --message "Clear stale close reason after reopen"','pm update pm-a1b2 --unset assignee --deadline +2d --message "Replan ownership and deadline"','pm update pm-a1b2 --body "Backfilled body text for legacy item" --message "Normalize missing body"'],tips:['Use "pm close <ID> <TEXT>" to close items instead of --status closed.',"When reopening from closed to a non-terminal status, update clears stale close_reason unless explicitly set via --close-reason.",'Use "pm append <ID> --body <text>" for additive notes; use update --body to replace body content.']},"update-many":{why:"Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.",examples:["pm update-many --filter-status open --status in_progress --dry-run",'pm update-many --filter-tag wave:7 --replace-tests --test "command=node scripts/run-tests.mjs test -- tests/core/history.spec.ts,timeout_seconds=240"','pm update-many --filter-tag governance --reviewer maintainer-review --message "Normalize reviewer metadata"',"pm update-many --rollback ckpt-abc123"],tips:["Use --dry-run first to inspect proposed changes before apply mode.","Linked-array mutation flags mirror pm update semantics (for example --replace-tests, --clear-files, and repeatable --doc/--note seeds).","Checkpoints are enabled by default for apply mode and can be restored with --rollback."]},"close-many":{why:"Bulk-closes matched items with a shared reason routed through full pm close semantics (close validation, active-child orphan checks, blocked-edge cleanup) plus dry-run previews and rollback checkpoints \u2014 unlike update-many --status closed, which bypasses close validation.",examples:['pm close-many --filter-sprint S-12 --reason "Sprint S-12 acceptance criteria met" --dry-run','pm close-many --filter-tag wave:7 --reason "Superseded by redesign" --validate-close warn','pm close-many --ids pm-a,pm-b,pm-c --reason "Closed in batch" --resolution "Verified by integration suite"',"pm close-many --rollback close-many-20260604-abc123"],tips:["At least one filter (--filter-* or --ids) is required so close-many never matches every item.","Already-terminal matches are skipped by default; pass --force to re-close them.","Use --dry-run to preview matches plus per-item skip reasons and active-child orphan warnings before applying.","Checkpoints are enabled by default for apply mode; restore with --rollback <checkpoint-id>."]},templates:{why:"Saves, lists, and inspects reusable create option bundles for repeatable workflows.",examples:['pm templates save triage-default --title "Triage item" --description "..." --type Task --status open --priority 2 --message "Seed triage template"',"pm templates list","pm templates show triage-default"],tips:["Template names are positional arguments (`pm templates save <name>` and `pm templates show <name>`), not --name flags.","Combine templates with explicit create flags; explicit flags always override template defaults."]},deps:{why:"Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.",examples:["pm deps pm-a1b2","pm deps pm-a1b2 --format graph","pm deps pm-a1b2 --max-depth 2 --collapse repeated --summary"],tips:["Use --summary for lightweight counts when full graph payloads are unnecessary."]},list:{why:"Lists active items with deterministic filtering and ordering.",examples:["pm list --limit 20","pm list --type Task --priority 0 --tag release --status in_progress","pm list --compact --sort deadline --order asc","pm list --fields id,title,parent,type --sort parent --order asc"]},"list-all":{why:"Lists all item states (including terminal states) when you need full visibility.",examples:["pm list-all --limit 50","pm list-all --type Issue --include-body"]},"list-open":{why:"Shows work that is ready to claim and start.",examples:["pm list-open --priority 0 --limit 10"]},"list-in-progress":{why:"Tracks active execution and owner progress.",examples:["pm list-in-progress --priority 0 --limit 20"]},"list-blocked":{why:"Surfaces blocked work that needs intervention.",examples:["pm list-blocked --limit 20"]},"list-closed":{why:"Reviews completed work and closure outcomes.",examples:["pm list-closed --limit 20 --type Task"]},"list-canceled":{why:"Audits intentionally discontinued work.",examples:["pm list-canceled --limit 20"]},"list-draft":{why:"Finds incompletely defined items that need refinement before execution.",examples:["pm list-draft --limit 20"]},aggregate:{why:"Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.",examples:["pm aggregate --group-by parent,type --count","pm aggregate --group-by type,status --count","pm aggregate --group-by parent,type --count --status open --parent pm-feature01"],tips:["Current aggregate mode is grouped counts only, so pass --count explicitly."]},guide:{why:"Routes local progressive-disclosure documentation so agents can fetch only the context they need.",examples:["pm install guide-shell --project","pm guide","pm guide quickstart","pm guide commands --depth standard","pm guide skills --depth deep --format markdown","pm guide release --json"],tips:["Use brief depth for minimal token footprint, standard for excerpted docs, and deep for full local document rendering.","Use --list to force topic index output even when topic parsing is ambiguous."]},calendar:{why:"Provides deadline/reminder/event scheduling views for planning and coordination.",examples:["pm calendar","pm calendar --view agenda --from +0d --to +7d --tag release","pm calendar --view week --date 2026-04-06 --full-period --include deadlines,events","pm calendar --view month --tag release --format json"],tips:["Day/week/month views are anchored period windows; default mode clips the start to now unless --past or --full-period is set.","--full-period applies only to day/week/month views; use --from/--to to bound agenda windows."]},context:{why:"Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.",examples:["pm context","pm ctx --depth standard --limit 10","pm ctx --depth deep --tag release","pm ctx --section hierarchy --section progress --section blockers","pm context --depth standard --activity-limit 20 --stale-threshold 14d","pm context --from +0d --to +7d --format markdown --depth deep"],tips:["High-level focus contains Epics/Features and low-level focus contains Tasks/Issues/Chores/Decisions/Event/Reminder/Milestone/Meeting/Plan.","When no open or in-progress work exists, blocked items are shown as fallback context.","--depth brief (default) shows focus+agenda; standard adds hierarchy/activity/progress/workload; deep adds blockers/files/staleness/tests.","--section overrides --depth and selects specific sections: hierarchy, activity, progress, blockers, files, workload, staleness, tests.","Configure defaults via pm config project set context --default-depth standard --activity-limit 15."]},next:{why:"Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.",examples:["pm next","pm next --json","pm next --limit 3 --ready-only","pm next --parent pm-mpbb","pm next --tag release --format markdown"],tips:["Ready = active status, no open blockers, and no open children (a concrete leaf); the recommendation resumes in-progress work before starting new work.","An item is blocked when its scalar blocked_by or a blocked_by dependency points at a non-terminal item; the blocked list names the blockers to clear.","Containers (Epics/Features with open children) are never recommended directly \u2014 the actionable leaf beneath them is.","Use --parent to scope to one epic's subtree, or --ready-only to drop the blocked companion list for the tightest output."]},search:{why:"Finds relevant items by keyword, semantic, or hybrid retrieval modes.",examples:['pm search "lock stale retry" --mode keyword --limit 10','pm search "extension migration blockers" --mode hybrid --type Task --priority 0','pm search "Cross-Epic Realism Dependency Council" --mode keyword --title-exact'],tips:["Use --title-exact to require exact normalized title parity, or --phrase-exact to require full-phrase matches in item text fields.","Use --include-linked when linked docs/files/tests should influence scoring."]},eval:{why:"Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.",examples:["pm eval --json","pm eval --mode hybrid --k 10","pm eval --fail-under 0.6 --json","pm eval --queries ./my-eval.json --mode semantic"],tips:["Curate ground truth in <pmRoot>/search/eval-queries.json as an array of {query, relevant_ids, mode?} objects.","Wire --fail-under into CI to fail the build when aggregate nDCG@k drops below your baseline."]},reindex:{why:"Rebuilds search artifacts after large changes to item corpus or provider/vector config.",examples:["pm reindex --mode keyword","pm reindex --mode hybrid --progress --json"],tips:["Use --progress for non-interactive visibility during local embedding runs.","JSON output includes semantic stale/unchanged/embed/upsert counts so agents can gate long reindex work without parsing stderr."]},get:{why:"Shows details for one item by ID, with optional lower-token projections for agent loops.",examples:["pm get pm-a1b2","pm get pm-a1b2 --depth brief --json","pm get pm-a1b2 --fields id,title,status,parent,type --json","pm get pm-a1b2 --at 7 --fields id,title,status,body --json"],tips:["Default depth is standard for body plus linked artifacts without append-only logs; use brief for metadata-only checks or --full for complete history-heavy metadata.","Use --fields for the smallest deterministic item metadata payload when an agent only needs specific fields.","Schedule metadata is normalized under schedule; request schedule.start_at or schedule.location for narrow calendar reads.","Children are type-agnostic and include bounded deterministic samples plus continuation metadata when a parent has direct children.","Use --at <version|timestamp> for a verified read-only historical projection; reconstructed/as_of fields distinguish it from current state.","JSON output shape is { item, linked, claim_state, schedule, children }; body is nested at item.body (parity with list --include-body)."]},history:{why:"Inspects item mutation timeline and audit trail.",examples:["pm history pm-a1b2 --limit 20","pm history pm-a1b2 --full --verify"]},"history-compact":{why:"Compacts long history streams into a synthetic checkpoint while preserving replay integrity. Pass an item id for one stream, or a bulk selector (--ids/--all-over/--closed/--all-streams) to sweep many.",examples:["pm history-compact pm-a1b2 --dry-run",'pm history-compact pm-a1b2 --before 25 --message "Compact early history"',"pm history-compact --all-over 500 --dry-run","pm history-compact --closed","pm history-compact --ids pm-a1b2,pm-c3d4 --dry-run"]},activity:{why:"Reviews recent tracker-wide activity across items.",examples:["pm activity --limit 50","pm activity --full --id pm-a1b2 --limit 50","pm activity --id pm-a1b2 --op update --from -7d --to now","pm activity --json --stream rows --limit 200"],tips:["Use --stream with --json for line-delimited automation output; --from is inclusive and --to is exclusive."]},restore:{why:"Restores an item to a prior timestamp/version with history replay safety.",examples:['pm restore pm-a1b2 2026-04-01T00:00:00.000Z --message "Rollback to known-good state"']},close:{why:"Transitions work to terminal closed state with explicit rationale.",examples:['pm close pm-a1b2 "Done" --resolution "Delivered" --expected "Required outcome" --actual "Verified outcome" --release-assignment --validate-close warn','pm close pm-a1b2 "Done" --validate-close','pm close pm-a1b2 "Done" --validate-close off','pm close pm-a1b2 "Done" --validate-close strict']},delete:{why:"Removes an item while preserving history evidence and lock/ownership checks.",examples:['pm delete pm-a1b2 --message "Remove duplicate item"']},append:{why:"Adds implementation notes to body without replacing existing content.",examples:['pm append pm-a1b2 --body "Implemented retry with bounded backoff." --message "Record implementation detail"']},comments:{why:"Adds or reviews lightweight status updates linked to an item.",examples:['pm comments pm-a1b2 "Verified fix on Linux and macOS"','pm comments pm-a1b2 --add "Verified fix on Linux and macOS"','printf "%s\\n" "## Verification" "- linux pass" "- mac pass" | pm comments pm-a1b2 --stdin',"pm comments pm-a1b2 --file docs/release-evidence.md",'pm comments pm-a1b2 --add "text: verification note with commas, key-like words, and parser details"','pm comments pm-a1b2 --add "Follow-up needed after review" --force',"pm comments pm-a1b2 --limit 10"],tips:["Use exactly one comment source at a time: positional [text], --add, --stdin, or --file.","Use --force when adding comments to items currently assigned to a different owner.","When --add payload resembles CSV-like key fragments (for example text=hello,scope:project), plain-text fallback is intentional; use explicit text=..., markdown text: ..., or stdin token - for structured intent."]},notes:{why:"Adds or reviews durable implementation notes linked to an item.",examples:['pm notes pm-a1b2 --add "Investigated parser edge case and documented fallback logic."','pm notes pm-a1b2 --add "text: parser rationale with commas, colons, and key-like wording"','pm notes pm-a1b2 --edit 1 --add "Corrected durable note"',"pm notes pm-a1b2 --delete 2","pm notes pm-a1b2 --limit 10"],tips:["CSV-like add payloads with extra key fragments are treated as plain text by design; use explicit text keys (text= or text:) when structured parsing is required."]},learnings:{why:"Adds or reviews post-implementation learnings for future work.",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 --delete 2","pm learnings pm-a1b2 --limit 10"],tips:["If you intended structured parsing for a key-like payload, prefer explicit text=..., markdown text: ..., or stdin token -; ambiguous CSV-like forms intentionally remain plain text."]},files:{why:"Associates changed source files with tracker items for reproducibility.",examples:['pm files pm-a1b2 --add "path=src/cli/main.ts,note=help orchestration"','pm files pm-a1b2 --add src/cli/main.ts --note "help orchestration"',"pm files discover pm-a1b2",'pm files discover pm-a1b2 --apply --note "discovered from item text"']},docs:{why:"Associates relevant documentation paths with tracker items.",examples:['pm docs pm-a1b2 --add "path=README.md,note=user-facing command guidance"','pm docs pm-a1b2 --add README.md --note "user-facing command guidance"']},test:{why:"Links test commands/paths and optionally executes them for one item.",examples:['pm test pm-a1b2 --add "command=node scripts/run-tests.mjs test -- tests/unit/output.spec.ts,timeout_seconds=2400"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,assert_stdout_contains=count:,assert_stdout_regex=count:\\s+\\d+"','pm test pm-a1b2 --add "command=pm list-all --type Task --limit 200,pm_context_mode=auto"',"pm test pm-a1b2 --run --timeout 2400 --env-set PORT=0 --env-clear PLAYWRIGHT_BASE_URL --shared-host-safe --pm-context tracker --fail-on-context-mismatch --fail-on-skipped","pm test pm-a1b2 --run --timeout 2400 --pm-context auto","pm test pm-a1b2 --run --background --timeout 2400 --progress"]},"test-all":{why:"Runs linked tests in bulk for release/readiness sweeps.",examples:["pm test-all --status in_progress --limit 5 --offset 10 --timeout 2400","pm test-all --status closed --timeout 3600 --progress --env-set PORT=0 --shared-host-safe --fail-on-skipped","pm test-all --status in_progress --pm-context tracker --fail-on-context-mismatch --require-assertions-for-pm","pm test-all --status in_progress --pm-context auto --fail-on-context-mismatch","pm test-all --status in_progress --background --timeout 3600"]},"test-runs":{why:"Manages background linked-test runs with lifecycle controls and log/status inspection.",examples:["pm test-runs list --status running --limit 20","pm test-runs status tr-abc123","pm test-runs logs tr-abc123 --stream stderr --tail 200","pm test-runs stop tr-abc123","pm test-runs resume tr-abc123"]},stats:{why:"Reports tracker-level totals and distribution by type/status.",examples:["pm stats","pm stats --json"]},telemetry:{why:"Inspects and manages local telemetry queue/runtime state for observability diagnostics.",examples:["pm telemetry status","pm telemetry stats --limit 10","pm telemetry flush","pm telemetry clear"]},health:{why:"Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.",examples:["pm health","pm health --check-only --summary --json","pm health --brief --json","pm health --no-refresh","pm health --refresh-vectors"]},validate:{why:"Runs standalone metadata, resolution, lifecycle (including dependency-cycle diagnostics), linked-file, linked-command reference, and history drift checks with default remediation hints for resolution gaps.",examples:["pm validate","pm validate --check-resolution --json","pm validate --check-lifecycle --dependency-cycle-severity error","pm validate --check-lifecycle --parent-cycle-severity error","pm validate --check-files --scan-mode tracked-all","pm validate --check-files --scan-mode tracked-all-strict --include-pm-internals","pm validate --check-command-references","pm validate --check-resolution --fail-on-warn --json"],tips:["Resolution-gap warnings include default `pm update <id> ...` remediation hint templates in check details."]},gc:{why:"Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.",examples:["pm gc --dry-run","pm gc"]},claim:{why:"Claims an item to signal active ownership and reduce conflicts.",examples:["pm claim pm-a1b2 --start",'pm claim pm-a1b2 --force --message "Take over terminal item"','pm claim pm-a1b2 --author "release-service" --message "Explicit non-agent identity override"'],tips:["Claim is an atomic test-and-set: a non-terminal item held by another principal refuses with already_claimed_by. Use --if-available to skip that item without failing. Terminal items still require --force, even when --if-available is set. Use --force for coordinated takeovers; stale locks require --force only when governance.force_required_for_stale_lock is enabled.","Harness identity is automatic; use --author only to assert an intentional external principal."]},release:{why:"Releases an active claim when paused, handed off, or completed.",examples:["pm release pm-a1b2 --pause",'pm release pm-a1b2 --handoff review --message "Implemented; run linked verification"'],tips:["Register the project queue with pm schema add-status review --role active before using --handoff."]},"start-task":{why:"Lifecycle alias that claims an item and sets status to in_progress.",examples:['pm start-task pm-a1b2 --message "Start implementation"']},"pause-task":{why:"Lifecycle alias that sets status to open and releases active assignment.",examples:['pm pause-task pm-a1b2 --message "Pause for dependency unblock"']},"close-task":{why:"Lifecycle alias that closes with reason text and clears assignment metadata.",examples:['pm close-task pm-a1b2 "All acceptance criteria met" --message "Close and handoff"']},meet:{why:"Shortcut to create a Meeting from friendly time flags (start/duration) without structured --event CSV.",examples:['pm meet "Sprint Planning" --start +1h --duration 1h','pm meet "1:1" --start 2026-07-01T15:00:00Z --end 2026-07-01T15:30:00Z --location "Room A"'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},event:{why:"Shortcut to create an Event from friendly time flags (start/duration) without structured --event CSV.",examples:['pm event "Release v2" --start 2026-07-01T10:00:00Z --duration 2h','pm event "Conference" --start 2026-08-01 --all-day'],tips:["Start defaults to now and duration to 1h; pass --end to set an explicit end instead of --duration.","--duration accepts relative tokens (h/d/w/m where m is months) plus sub-hour forms like 30min or PT30M."]},remind:{why:"Shortcut to create a Reminder from a single point in time without structured --reminder CSV.",examples:['pm remind "Review PR" --at +2d','pm remind "Follow up" --at 2026-07-01T09:00:00Z --text "Ping the team"'],tips:["The reminder time defaults to +1d and the reminder text defaults to the title."]},completion:{why:"Generates shell completion scripts for faster and more reliable command entry.",examples:["pm completion bash","pm completion zsh","pm completion fish","pm completion bash --eager-tags"],tips:["Default scripts resolve tag suggestions lazily at completion time; use --eager-tags to embed current tags directly."]},contracts:{why:"Exposes machine-readable CLI command and tool schema contracts for agent integrations.",examples:["pm contracts","pm contracts --command list --runtime-only","pm contracts --command update --flags-only","pm contracts --availability-only --runtime-only","pm contracts --action create","pm contracts --schema-only"],tips:["Use --command to narrow actions/schema to one CLI surface; combine with --flags-only or --availability-only for lighter payloads."]}};for(const{alias,canonical}of PM_RELOCATED_COMMAND_ALIASES){const bundle=HELP_BY_COMMAND_PATH[alias];bundle&&(HELP_BY_COMMAND_PATH[canonical]={...bundle,examples:bundle.examples.map(example=>example.replace(`pm ${alias}`,`pm ${canonical}`))})}const ROOT_HELP_BUNDLE={why:"Provides deterministic project management workflows for humans and coding agents.",examples:["pm init","pm install guide-shell --project","pm list-open --limit 10",'pm create --title "..." --description "..." --type Task --status open --priority 1 --message "..." --create-mode progressive'],tips:["Use <command> --help for command-specific guidance and examples.","Install guide-shell before using pm guide for local docs and skills routing.","Use --json for machine parsing and integration flows.","Use --no-pager to force direct help output in CI and other non-interactive shells."]},deprecatedHelpAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(entry=>entry.lifecycle==="deprecated");for(const contract of deprecatedHelpAliases){const bundle=HELP_BY_COMMAND_PATH[contract.alias];HELP_BY_COMMAND_PATH[contract.alias]={...bundle,why:`Deprecated: use pm ${contract.canonical_argv.join(" ")}. ${bundle.why}`}}for(const bundle of[ROOT_HELP_BUNDLE,...Object.values(HELP_BY_COMMAND_PATH)])bundle.examples=bundle.examples.map(example=>{for(const contract of deprecatedHelpAliases){const alias=contract.alias.replace(/[.*+?^${}()|[\]\\]/g,"\\$&");example=example.replaceAll(new RegExp(`\\bpm ${alias}(?![\\w-])`,"g"),`pm ${contract.canonical_argv.join(" ")}`)}return example});function resolveCanonicalHelpPath(commandPath){const normalized=normalizeHelpCommandPath(commandPath??"");return normalized?HELP_PATH_ALIASES[normalized]??normalized:""}function resolveHelpBundleForPath(commandPath){const canonicalPath=resolveCanonicalHelpPath(commandPath);return canonicalPath?HELP_BY_COMMAND_PATH[canonicalPath]??ROOT_HELP_BUNDLE:ROOT_HELP_BUNDLE}function resolveHelpNarrative(commandPath,detailMode){const bundle=resolveHelpBundleForPath(commandPath);return{intent:bundle.why,examples:detailMode==="detailed"?[...bundle.examples]:firstExampleOrEmpty(bundle.examples),tips:detailMode==="detailed"?[...bundle.tips??[]]:[],detail_mode:detailMode}}function renderFullCommandAliasHelp(){const permanentAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="permanent"),deprecatedAliases=PM_COMMAND_ALIAS_CONTRACTS.filter(({lifecycle})=>lifecycle==="deprecated");return["","Command aliases:",...permanentAliases.map(({alias,canonical_argv:canonicalArgv})=>`  ${alias} -> pm ${canonicalArgv.join(" ")}`),"","Deprecated aliases:",...deprecatedAliases.map(contract=>`  ${contract.alias} -> pm ${contract.canonical_argv.join(" ")} (${renderPmCommandAliasMigrationHint(contract)})`)].join(`
 `)}function configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands){const coreOptions=new Set(PM_CORE_HELP_OPTION_FLAGS);program.configureHelp({visibleCommands(command){const visible=baselineHelp.visibleCommands(command);return fullDiscovery?visible.filter(candidate=>(getPmCommandHelpVisibilityTier(candidate)??resolvePmCommandVisibilityTier(candidate.name()))!=="internal"):command!==program?visible:visible.filter(candidate=>selectedRootCommands.has(candidate))},visibleOptions(command){const visible=baselineHelp.visibleOptions(command);return command!==program||fullDiscovery?visible:visible.filter(option=>coreOptions.has(option.flags))}});const continuationOptions=program.options.filter(option=>option.long==="--output-cursor");for(const command of program.commands.flatMap(root=>[root,...root.commands]))["list","search","context"].includes(command.name())&&command.configureHelp({visibleOptions:target=>[...baselineHelp.visibleOptions(target),...continuationOptions]})}function selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText){const coreCommands=new Set(listPmCommandsForTier("core")),budgetHelp=program.createHelp();budgetHelp.prepareContext({error:!1,helpWidth:80,outputHasColors:!1});const renderBudgetHelp=()=>`${budgetHelp.formatHelp(program,budgetHelp)}${rootHelpText}
 `,rootCandidates=baselineHelp.visibleCommands(program);for(const candidate of rootCandidates)getPmCommandHelpVisibilityTier(candidate)===void 0&&(candidate.name()==="help"||coreCommands.has(candidate.name()))&&selectedRootCommands.add(candidate);for(const candidate of rootCandidates)getPmCommandHelpVisibilityTier(candidate)==="core"&&(selectedRootCommands.add(candidate),measurePmCoreHelp(renderBudgetHelp()).within_budget||selectedRootCommands.delete(candidate))}function attachRichHelpText(program,argv=process.argv.slice(2)){const baselineHelp=program.createHelp(),fullDiscovery=isFullHelpDiscovery(argv),selectedRootCommands=new Set;configureTieredHelpVisibility(program,baselineHelp,fullDiscovery,selectedRootCommands);const detailMode=resolveHelpDetailMode(argv),rootHelpText=renderHelpBundle(ROOT_HELP_BUNDLE,detailMode);program.addHelpText("after",rootHelpText),fullDiscovery&&program.addHelpText("after",renderFullCommandAliasHelp()),selectBudgetedRootCommands(program,baselineHelp,selectedRootCommands,rootHelpText);for(const[commandPath,bundle]of Object.entries(HELP_BY_COMMAND_PATH))attachBundleByPath(program,commandPath,bundle,detailMode);const requestedPath=normalizeHelpCommandPath(parseBootstrapHelpRequest(argv).commandPathTokens.join(" ")),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);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)}const _testOnly={renderCompactHelpBundle,renderDetailedHelpBundle};export{ROOT_HELP_BUNDLE,_testOnly,attachRichHelpText,firstExampleOrEmpty,getPmCommandHelpVisibilityTier,isFullHelpDiscovery,normalizeHelpCommandPath,resolveHelpBundleForPath,resolveHelpDetailMode,resolveHelpNarrative,setPmCommandHelpVisibilityTier};
 //# sourceMappingURL=help-content.js.map

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

@@ -1,6 +1,6 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b333763a-2ae3-5a36-9d09-a7fd3b8ee735")}catch{}})();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";import{applyContextIntentProjection}from"../sdk/context-intent-contracts.js";import{renderPmClosedDomainHelp}from"../sdk/agent/closed-domain-contracts.js";import{serializeNdjsonRows,serializeNdjsonStream}from"../sdk/output.js";import{listMutationEvents,subscribeMutationEventBatches,subscribeMutationEvents}from"../sdk/mutation-events.js";import{registerHistoryActivityCommand}from"./register-history-activity.js";import{registerHistoryMaintenanceCommands}from"./register-history-maintenance.js";import{runAggregate}from"./commands/query/aggregate.js";import{renderContextMarkdown,runContext,resolveContextOutputFormat}from"./commands/query/context.js";import{runEval}from"./commands/query/eval.js";import{runGet}from"./commands/query/get.js";import{runGraph}from"./commands/query/graph.js";import{runHistory}from"./commands/history/history.js";import{runList}from"./commands/query/list.js";import{LIST_COMMAND_DEFAULT_PROJECTIONS}from"../sdk/query/list.js";import{renderNextMarkdown,runNext,resolveNextOutputFormat}from"./commands/query/next.js";import{runSearch}from"./commands/query/search.js";import{addHiddenOption,collect,getGlobalOptions,normalizeAggregateOptions,normalizeContextOptions,normalizeListOptions,normalizeNextOptions,normalizeSearchKeywordsInput,normalizeSearchOptions,printError,printListJsonStream,printResult,setActiveCommandResult,writeStdout}from"./registration-helpers.js";function shouldRegisterListQueryCommand(commandName,commandFilter){return!commandFilter||commandFilter.size===0?!0:commandName==="context"?commandFilter.has("context")||commandFilter.has("ctx"):commandFilter.has(commandName)}function parseListFormat(rawFormat){if(rawFormat===void 0)return;if(typeof rawFormat!="string")throw new PmCliError("List --format must be one of csv|table|json|ndjson|toon",EXIT_CODE.USAGE);const normalized=rawFormat.trim().toLowerCase();if(normalized==="csv"||normalized==="table"||normalized==="json"||normalized==="ndjson"||normalized==="toon")return normalized;throw new PmCliError("List --format must be one of csv|table|json|ndjson|toon",EXIT_CODE.USAGE)}function resolveReadCommandOutputFormat(commandLabel,rawFormat,globalOptions,allowNdjson=!1){if(rawFormat===void 0)return globalOptions;if(typeof rawFormat!="string")throw new PmCliError(`${commandLabel} --format must be one of ${allowNdjson?"json|ndjson|toon":"json|toon"}`,EXIT_CODE.USAGE);const normalized=rawFormat.trim().toLowerCase();if(normalized!=="json"&&(normalized!=="ndjson"||!allowNdjson)&&normalized!=="toon")throw new PmCliError(`${commandLabel} --format must be one of ${allowNdjson?"json|ndjson|toon":"json|toon"}`,EXIT_CODE.USAGE);if(globalOptions.json===!0&&normalized==="toon")throw new PmCliError(`${commandLabel} cannot combine --json with --format toon`,EXIT_CODE.USAGE);return{...globalOptions,json:normalized==="json"||normalized==="ndjson"}}function applyDefaultListProjection(listOptions,commandName){LIST_COMMAND_DEFAULT_PROJECTIONS[commandName]==="brief"&&listOptions.includeBody!==!0&&listOptions.compact!==!0&&listOptions.brief!==!0&&listOptions.full!==!0&&listOptions.fields===void 0&&(listOptions.brief=!0)}function registerContentAndGovernanceFilters(command){command.option("--has-notes","Show only items that have notes").option("--has-learnings","Show only items that have learnings").option("--has-files","Show only items that have linked files").option("--has-docs","Show only items that have linked docs").option("--has-tests","Show only items that have linked tests").option("--has-comments","Show only items that have comments").option("--has-deps","Show only items that have dependencies").option("--has-body","Show only items that have a non-empty body").option("--has-linked-command","Show only items whose linked tests carry a runnable command").option("--no-notes","Show only items that have no notes").option("--no-learnings","Show only items that have no learnings").option("--no-files","Show only items that have no linked files").option("--filter-files-missing","Alias for --no-files").option("--no-docs","Show only items that have no linked docs").option("--filter-docs-missing","Alias for --no-docs").option("--no-tests","Show only items that have no linked tests").option("--no-comments","Show only items that have no comments").option("--no-deps","Show only items that have no dependencies").option("--empty-body","Show only items with an empty body").option("--no-linked-command","Show only items whose linked tests carry no runnable command").option("--filter-reviewer-missing","Show only items missing reviewer").option("--filter-risk-missing","Show only items missing risk").option("--filter-confidence-missing","Show only items missing confidence").option("--filter-sprint-missing","Show only items missing sprint").option("--filter-release-missing","Show only items missing release")}const CANONICAL_LIST_STATUS_VARIANTS={draft:{name:"list-draft",dependencyBlocked:!1},open:{name:"list-open",dependencyBlocked:!1},in_progress:{name:"list-in-progress",dependencyBlocked:!1},blocked:{name:"list-blocked",dependencyBlocked:!0},closed:{name:"list-closed",dependencyBlocked:!1},canceled:{name:"list-canceled",dependencyBlocked:!1}};function resolveRegisteredListOutputContext(options,globalOptions){const streamMode=options.stream===!0,listFormat=parseListFormat(options.format),tabular=listFormat==="csv"||listFormat==="table",effectiveGlobal=listFormat==="json"||listFormat==="ndjson"||listFormat==="toon"?resolveReadCommandOutputFormat("List",options.format,globalOptions,!0):globalOptions;if(streamMode&&!effectiveGlobal.json)throw new PmCliError("--stream requires --json output mode.",EXIT_CODE.USAGE);if((tabular||listFormat==="ndjson")&&streamMode)throw new PmCliError("--format csv|table|ndjson cannot be combined with --stream.",EXIT_CODE.USAGE);return{streamMode,listFormat,effectiveGlobal}}function renderRegisteredListResult(commandName,result,output){if(output.listFormat==="csv"||output.listFormat==="table"){setActiveCommandResult(result);const rows=result.items,rendered=output.listFormat==="csv"?renderRowsAsCsv(rows):renderRowsAsTable(rows);!output.effectiveGlobal.quiet&&rendered.length>0&&writeStdout(`${rendered}
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3ba7d2b3-a8e8-5128-8487-5f31af0183c6")}catch{}})();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";import{applyContextIntentProjection}from"../sdk/context-intent-contracts.js";import{renderPmClosedDomainHelp}from"../sdk/agent/closed-domain-contracts.js";import{serializeNdjsonRows,serializeNdjsonStream}from"../sdk/output.js";import{listMutationEvents,subscribeMutationEventBatches,subscribeMutationEvents}from"../sdk/mutation-events.js";import{registerHistoryActivityCommand}from"./register-history-activity.js";import{registerHistoryMaintenanceCommands}from"./register-history-maintenance.js";import{runAggregate}from"./commands/query/aggregate.js";import{renderContextMarkdown,runContext,resolveContextOutputFormat}from"./commands/query/context.js";import{runEval}from"./commands/query/eval.js";import{runGet}from"./commands/query/get.js";import{runGraph}from"./commands/query/graph.js";import{runHistory}from"./commands/history/history.js";import{runList}from"./commands/query/list.js";import{LIST_COMMAND_DEFAULT_PROJECTIONS}from"../sdk/query/list.js";import{renderNextMarkdown,runNext,resolveNextOutputFormat}from"./commands/query/next.js";import{runSearch}from"./commands/query/search.js";import{addHiddenOption,collect,getGlobalOptions,normalizeAggregateOptions,normalizeContextOptions,normalizeListOptions,normalizeNextOptions,normalizeSearchKeywordsInput,normalizeSearchOptions,printError,printListJsonStream,printResult,setActiveCommandResult,writeStdout}from"./registration-helpers.js";function shouldRegisterListQueryCommand(commandName,commandFilter){return!commandFilter||commandFilter.size===0?!0:commandName==="context"?commandFilter.has("context")||commandFilter.has("ctx"):commandFilter.has(commandName)}function parseListFormat(rawFormat){if(rawFormat===void 0)return;if(typeof rawFormat!="string")throw new PmCliError("List --format must be one of csv|table|json|ndjson|toon",EXIT_CODE.USAGE);const normalized=rawFormat.trim().toLowerCase();if(normalized==="csv"||normalized==="table"||normalized==="json"||normalized==="ndjson"||normalized==="toon")return normalized;throw new PmCliError("List --format must be one of csv|table|json|ndjson|toon",EXIT_CODE.USAGE)}function resolveReadCommandOutputFormat(commandLabel,rawFormat,globalOptions,allowNdjson=!1){if(rawFormat===void 0)return globalOptions;if(typeof rawFormat!="string")throw new PmCliError(`${commandLabel} --format must be one of ${allowNdjson?"json|ndjson|toon":"json|toon"}`,EXIT_CODE.USAGE);const normalized=rawFormat.trim().toLowerCase();if(normalized!=="json"&&(normalized!=="ndjson"||!allowNdjson)&&normalized!=="toon")throw new PmCliError(`${commandLabel} --format must be one of ${allowNdjson?"json|ndjson|toon":"json|toon"}`,EXIT_CODE.USAGE);if(globalOptions.json===!0&&normalized==="toon")throw new PmCliError(`${commandLabel} cannot combine --json with --format toon`,EXIT_CODE.USAGE);return{...globalOptions,json:normalized==="json"||normalized==="ndjson"}}function applyDefaultListProjection(listOptions,commandName){LIST_COMMAND_DEFAULT_PROJECTIONS[commandName]==="brief"&&listOptions.includeBody!==!0&&listOptions.compact!==!0&&listOptions.brief!==!0&&listOptions.full!==!0&&listOptions.fields===void 0&&(listOptions.brief=!0)}function registerContentAndGovernanceFilters(command){command.option("--has-notes","Show only items that have notes").option("--has-learnings","Show only items that have learnings").option("--has-files","Show only items that have linked files").option("--has-docs","Show only items that have linked docs").option("--has-tests","Show only items that have linked tests").option("--has-comments","Show only items that have comments").option("--has-deps","Show only items that have dependencies").option("--has-body","Show only items that have a non-empty body").option("--has-linked-command","Show only items whose linked tests carry a runnable command").option("--no-notes","Show only items that have no notes").option("--no-learnings","Show only items that have no learnings").option("--no-files","Show only items that have no linked files").option("--filter-files-missing","Alias for --no-files").option("--no-docs","Show only items that have no linked docs").option("--filter-docs-missing","Alias for --no-docs").option("--no-tests","Show only items that have no linked tests").option("--no-comments","Show only items that have no comments").option("--no-deps","Show only items that have no dependencies").option("--empty-body","Show only items with an empty body").option("--no-linked-command","Show only items whose linked tests carry no runnable command").option("--filter-reviewer-missing","Show only items missing reviewer").option("--filter-risk-missing","Show only items missing risk").option("--filter-confidence-missing","Show only items missing confidence").option("--filter-sprint-missing","Show only items missing sprint").option("--filter-release-missing","Show only items missing release")}const CANONICAL_LIST_STATUS_VARIANTS={draft:{name:"list-draft",dependencyBlocked:!1},open:{name:"list-open",dependencyBlocked:!1},in_progress:{name:"list-in-progress",dependencyBlocked:!1},blocked:{name:"list-blocked",dependencyBlocked:!0},closed:{name:"list-closed",dependencyBlocked:!1},canceled:{name:"list-canceled",dependencyBlocked:!1}};function resolveRegisteredListOutputContext(options,globalOptions){const streamMode=options.stream===!0,listFormat=parseListFormat(options.format),tabular=listFormat==="csv"||listFormat==="table",effectiveGlobal=listFormat==="json"||listFormat==="ndjson"||listFormat==="toon"?resolveReadCommandOutputFormat("List",options.format,globalOptions,!0):globalOptions;if(streamMode&&!effectiveGlobal.json)throw new PmCliError("--stream requires --json output mode.",EXIT_CODE.USAGE);if((tabular||listFormat==="ndjson")&&streamMode)throw new PmCliError("--format csv|table|ndjson cannot be combined with --stream.",EXIT_CODE.USAGE);return{streamMode,listFormat,effectiveGlobal}}function renderRegisteredListResult(commandName,result,output){if(output.listFormat==="csv"||output.listFormat==="table"){setActiveCommandResult(result);const rows=result.items,rendered=output.listFormat==="csv"?renderRowsAsCsv(rows):renderRowsAsTable(rows);!output.effectiveGlobal.quiet&&rendered.length>0&&writeStdout(`${rendered}
 `)}else if(output.listFormat==="ndjson"){setActiveCommandResult(result);const rendered=serializeNdjsonRows(result.items);!output.effectiveGlobal.quiet&&rendered.length>0&&writeStdout(`${rendered}
-`)}else output.streamMode?printListJsonStream(commandName,result,output.effectiveGlobal):printResult(result,output.effectiveGlobal)}async function runRegisteredListCommand(params){const parsedGlobalOptions=getGlobalOptions(params.actionCommand),globalOptions=params.aliasContract?{...parsedGlobalOptions,command:params.aliasContract.canonical}:parsedGlobalOptions,startedAt=Date.now();params.aliasContract?.lifecycle==="deprecated"&&await readSettings(resolvePmRoot(process.cwd(),globalOptions.path)).then(settings=>settings.ux.deprecation_hints)&&printError(renderPmCommandAliasMigrationHint(params.aliasContract));const intentOptions=applyContextIntentProjection("list",params.options),listOptions=normalizeListOptions(intentOptions),selection=resolveRegisteredListSelection(params,listOptions),{effectiveName,effectiveStatus,effectiveDependencyBlocked,effectiveExcludeTerminal}=selection;applyDefaultListProjection(listOptions,effectiveName),Object.assign(listOptions,{projectionCommand:effectiveName}),effectiveExcludeTerminal&&(listOptions.excludeTerminal=!0),listOptions.dependencyBlocked=effectiveDependencyBlocked;const output=resolveRegisteredListOutputContext(intentOptions,globalOptions),result=await runList(effectiveDependencyBlocked?void 0:effectiveStatus,listOptions,globalOptions);renderRegisteredListResult("list",result,output),globalOptions.profile&&printError(`profile:command=list took_ms=${Date.now()-startedAt}`)}function resolveRegisteredListSelection(params,listOptions){let effectiveName=params.name,effectiveStatus=params.status,effectiveDependencyBlocked=params.dependencyBlocked===!0,effectiveExcludeTerminal=params.excludeTerminal===!0;const requestedStatus=listOptions.status?.trim().toLowerCase(),requestedVariant=params.name==="list"&&requestedStatus!==void 0?CANONICAL_LIST_STATUS_VARIANTS[requestedStatus]:void 0;return params.name==="list"&&(params.options.all===!0||requestedStatus==="all"?(effectiveName="list-all",effectiveExcludeTerminal=!1,listOptions.status=void 0):requestedStatus!==void 0&&requestedVariant!==void 0&&(effectiveName=requestedVariant.name,effectiveStatus=requestedStatus,effectiveDependencyBlocked=requestedVariant.dependencyBlocked,effectiveExcludeTerminal=!1,listOptions.status=void 0)),(effectiveName==="list-open"||effectiveName==="list-in-progress")&&(listOptions.lifecycleBucket=effectiveName==="list-open"?"open":"in_progress",effectiveStatus=void 0),{effectiveName,effectiveStatus,effectiveDependencyBlocked,effectiveExcludeTerminal}}function registerListCommand(program,descriptor){const{name,description,status,excludeTerminal,allowStatusFilter,dependencyBlocked,aliasContract}=descriptor,command=program.command(name,{hidden:aliasContract?.hidden===!0}).description(description);allowStatusFilter&&command.option("--status <value>","Filter by status (repeatable or comma-separated; matches any; all selects every status)",collect),name==="list"&&command.option("--all","Include every lifecycle status"),command.option("--for <intent>",`Apply a declared context intent projection. ${renderPmClosedDomainHelp("list","--for")}`).option("--token-budget <n>","Override the selected intent's maximum estimated output tokens").option("--type <value>","Filter by item type (repeatable or comma-separated; matches any)",collect).option("--tag <value>","Filter by tag (repeatable or comma-separated; matches any)",collect).option("--priority <value>","Filter by priority (repeatable or comma-separated; matches any)",collect).option("--deadline-before <value>","Filter by deadline upper bound (ISO/date string or relative)").option("--deadline-after <value>","Filter by deadline lower bound (ISO/date string or relative)").option("--today","Filter to items updated since local midnight today").option("--recent","Filter to items updated in the last 7 days").option("--updated-after <value>","Updated since ISO timestamp or signed relative (-2h/-7d for past); use last-window ISO").option("--updated-before <value>","Filter by updated_at upper bound: ISO timestamp or signed relative (-2h/+1d)").option("--created-after <value>","Filter by created_at lower bound: ISO timestamp or signed relative (-2h/+1d)").option("--created-before <value>","Filter by created_at upper bound: ISO timestamp or signed relative (-2h/+1d)").option("--ids <value>","Filter by explicit item IDs (comma-separated or repeatable)").option("--assignee <value>","Filter by assignee",collect).option("--assignee-filter <value>","Filter assignee presence: assigned|unassigned").option("--parent <value>","Filter by parent item ID").option("--sprint <value>","Filter by sprint",collect).option("--release <value>","Filter by release",collect).option("--filter-ac-missing","Show only items missing acceptance_criteria").option("--filter-estimates-missing","Show only items missing estimated_minutes").option("--filter-resolution-missing","Show only terminal items missing resolution").option("--filter-metadata-missing","Show only items missing any tracked metadata (AC, estimate, or resolution)").option("--limit <n>","Alias for --output-limit; --output-budget may cap rows").option("--offset <n>","Skip the first n matching rows before limit is applied").option("--after <cursor>","Query next_cursor; output_cursor uses --output-cursor").option("--no-truncate","Disable default token cap; explicit --limit and --output-budget apply").option("--include-body","Include item body in each returned list row").option("--strict-read","Fail closed if any item document or item directory cannot be read").option("--compact","Render compact list projection fields (mutually exclusive with --brief/--full/--fields)").option("--brief","Ultra-compact output: id, status, type, title only (agent-optimized, mutually exclusive with --compact/--full/--fields)").option("--full","Render full list projection fields (mutually exclusive with --compact/--brief/--fields)").option("--fields <value>",`Render custom comma-separated list fields (mutually exclusive with --compact/--brief/--full). ${renderPmClosedDomainHelp(name,"--fields")}`).option("--sort <value>","Sort field: priority|deadline|updated_at|created_at|title|parent (aliases: updated, created)").option("--order <value>","Sort order: asc|desc (requires --sort)").option("--tree","Render rows in parent/child tree order").option("--tree-depth <n>","Maximum recursion depth with --tree (0 keeps root rows only)").option("--format <value>","Output render mode: csv|table (human export) or json|ndjson|toon (machine output override)").option("--stream","Emit line-delimited JSON rows (requires --json)"),registerContentAndGovernanceFilters(command),command.action(async(options,actionCommand)=>{await runRegisteredListCommand({name,status,excludeTerminal,dependencyBlocked,options,actionCommand,aliasContract})}),addHiddenOption(command,"--tags <value>","Alias for --tag"),addHiddenOption(command,"--assignee_filter <value>","Alias for --assignee-filter"),addHiddenOption(command,"--tree_depth <n>","Alias for --tree-depth"),addHiddenOption(command,"--token_budget <n>","Alias for --token-budget"),addHiddenOption(command,"--filter-estimate-missing","Alias for --filter-estimates-missing")}async function runAggregateAction(options,command){const globalOptions=getGlobalOptions(command),startedAt=Date.now(),result=await runAggregate(normalizeAggregateOptions(options),globalOptions);printResult(result,globalOptions),globalOptions.profile&&printError(`profile:command=aggregate took_ms=${Date.now()-startedAt}`)}async function runContextAction(options,actionCommand){const globalOptions=getGlobalOptions(actionCommand),startedAt=Date.now(),normalized=normalizeContextOptions(applyContextIntentProjection("context",options)),result=await runContext(normalized,globalOptions),outputFormat=resolveContextOutputFormat(normalized,globalOptions);if(outputFormat==="markdown")globalOptions.quiet||writeStdout(`${renderContextMarkdown(result)}
+`)}else output.streamMode?printListJsonStream(commandName,result,output.effectiveGlobal):printResult(result,output.effectiveGlobal)}async function runRegisteredListCommand(params){const parsedGlobalOptions=getGlobalOptions(params.actionCommand),globalOptions=params.aliasContract?{...parsedGlobalOptions,command:params.aliasContract.canonical}:parsedGlobalOptions,startedAt=Date.now();params.aliasContract?.lifecycle==="deprecated"&&await readSettings(resolvePmRoot(process.cwd(),globalOptions.path)).then(settings=>settings.ux.deprecation_hints)&&printError(renderPmCommandAliasMigrationHint(params.aliasContract));const intentOptions=applyContextIntentProjection("list",params.options),listOptions=normalizeListOptions(intentOptions),selection=resolveRegisteredListSelection(params,listOptions),{effectiveName,effectiveStatus,effectiveDependencyBlocked,effectiveExcludeTerminal}=selection;applyDefaultListProjection(listOptions,params.name),Object.assign(listOptions,{projectionCommand:effectiveName}),effectiveExcludeTerminal&&(listOptions.excludeTerminal=!0),listOptions.dependencyBlocked=effectiveDependencyBlocked;const output=resolveRegisteredListOutputContext(intentOptions,globalOptions),result=await runList(effectiveDependencyBlocked?void 0:effectiveStatus,listOptions,globalOptions);renderRegisteredListResult("list",result,output),globalOptions.profile&&printError(`profile:command=list took_ms=${Date.now()-startedAt}`)}function resolveRegisteredListSelection(params,listOptions){let effectiveName=params.name,effectiveStatus=params.status,effectiveDependencyBlocked=params.dependencyBlocked===!0,effectiveExcludeTerminal=params.excludeTerminal===!0;const requestedStatus=listOptions.status?.trim().toLowerCase(),requestedVariant=params.name==="list"&&requestedStatus!==void 0?CANONICAL_LIST_STATUS_VARIANTS[requestedStatus]:void 0;return params.name==="list"&&(params.options.all===!0||requestedStatus==="all"?(effectiveName="list-all",effectiveExcludeTerminal=!1,listOptions.status=void 0):requestedStatus!==void 0&&requestedVariant!==void 0&&(effectiveName=requestedVariant.name,effectiveStatus=requestedStatus,effectiveDependencyBlocked=requestedVariant.dependencyBlocked,effectiveExcludeTerminal=!1,listOptions.status=void 0)),(effectiveName==="list-open"||effectiveName==="list-in-progress")&&(listOptions.lifecycleBucket=effectiveName==="list-open"?"open":"in_progress",effectiveStatus=void 0),{effectiveName,effectiveStatus,effectiveDependencyBlocked,effectiveExcludeTerminal}}function registerListCommand(program,descriptor){const{name,description,status,excludeTerminal,allowStatusFilter,dependencyBlocked,aliasContract}=descriptor,command=program.command(name,{hidden:aliasContract?.hidden===!0}).description(description);allowStatusFilter&&command.option("--status <value>","Filter by status (repeatable or comma-separated; matches any; all selects every status)",collect),name==="list"&&command.option("--all","Include every lifecycle status"),command.option("--for <intent>",`Apply a declared context intent projection. ${renderPmClosedDomainHelp("list","--for")}`).option("--token-budget <n>","Override the selected intent's maximum estimated output tokens").option("--type <value>","Filter by item type (repeatable or comma-separated; matches any)",collect).option("--tag <value>","Filter by tag (repeatable or comma-separated; matches any)",collect).option("--priority <value>","Filter by priority (repeatable or comma-separated; matches any)",collect).option("--deadline-before <value>","Filter by deadline upper bound (ISO/date string or relative)").option("--deadline-after <value>","Filter by deadline lower bound (ISO/date string or relative)").option("--today","Filter to items updated since local midnight today").option("--recent","Filter to items updated in the last 7 days").option("--updated-after <value>","Updated since ISO timestamp or signed relative (-2h/-7d for past); use last-window ISO").option("--updated-before <value>","Filter by updated_at upper bound: ISO timestamp or signed relative (-2h/+1d)").option("--created-after <value>","Filter by created_at lower bound: ISO timestamp or signed relative (-2h/+1d)").option("--created-before <value>","Filter by created_at upper bound: ISO timestamp or signed relative (-2h/+1d)").option("--ids <value>","Filter by explicit item IDs (comma-separated or repeatable)").option("--assignee <value>","Filter by assignee",collect).option("--assignee-filter <value>","Filter assignee presence: assigned|unassigned").option("--parent <value>","Filter by parent item ID").option("--sprint <value>","Filter by sprint",collect).option("--release <value>","Filter by release",collect).option("--filter-ac-missing","Show only items missing acceptance_criteria").option("--filter-estimates-missing","Show only items missing estimated_minutes").option("--filter-resolution-missing","Show only terminal items missing resolution").option("--filter-metadata-missing","Show only items missing any tracked metadata (AC, estimate, or resolution)").option("--limit <n>","Alias for --output-limit; --output-budget may cap rows").option("--offset <n>","Skip the first n matching rows before limit is applied").option("--after <cursor>","Query next_cursor; output_cursor uses --output-cursor").option("--no-truncate","Disable default token cap; explicit --limit and --output-budget apply").option("--include-body","Include item body in each returned list row").option("--strict-read","Fail closed if any item document or item directory cannot be read").option("--compact","Render compact list projection fields (mutually exclusive with --brief/--full/--fields)").option("--brief","Ultra-compact output: id, status, type, title only (agent-optimized, mutually exclusive with --compact/--full/--fields)").option("--full","Render full list projection fields (mutually exclusive with --compact/--brief/--fields)").option("--fields <value>",`Render custom comma-separated list fields (mutually exclusive with --compact/--brief/--full). ${renderPmClosedDomainHelp(name,"--fields")}`).option("--sort <value>","Sort field: priority|deadline|updated_at|created_at|title|parent (aliases: updated, created)").option("--order <value>","Sort order: asc|desc (requires --sort)").option("--tree","Render rows in parent/child tree order").option("--tree-depth <n>","Maximum recursion depth with --tree (0 keeps root rows only)").option("--format <value>","Output render mode: csv|table (human export) or json|ndjson|toon (machine output override)").option("--stream","Emit line-delimited JSON rows (requires --json)"),registerContentAndGovernanceFilters(command),command.action(async(options,actionCommand)=>{await runRegisteredListCommand({name,status,excludeTerminal,dependencyBlocked,options,actionCommand,aliasContract})}),addHiddenOption(command,"--tags <value>","Alias for --tag"),addHiddenOption(command,"--assignee_filter <value>","Alias for --assignee-filter"),addHiddenOption(command,"--tree_depth <n>","Alias for --tree-depth"),addHiddenOption(command,"--token_budget <n>","Alias for --token-budget"),addHiddenOption(command,"--filter-estimate-missing","Alias for --filter-estimates-missing")}async function runAggregateAction(options,command){const globalOptions=getGlobalOptions(command),startedAt=Date.now(),result=await runAggregate(normalizeAggregateOptions(options),globalOptions);printResult(result,globalOptions),globalOptions.profile&&printError(`profile:command=aggregate took_ms=${Date.now()-startedAt}`)}async function runContextAction(options,actionCommand){const globalOptions=getGlobalOptions(actionCommand),startedAt=Date.now(),normalized=normalizeContextOptions(applyContextIntentProjection("context",options)),result=await runContext(normalized,globalOptions),outputFormat=resolveContextOutputFormat(normalized,globalOptions);if(outputFormat==="markdown")globalOptions.quiet||writeStdout(`${renderContextMarkdown(result)}
 `);else if(outputFormat==="ndjson"){setActiveCommandResult(result);const rendered=serializeNdjsonRows([...result.high_level,...result.low_level,...result.blocked_fallback]);!globalOptions.quiet&&rendered.length>0&&writeStdout(`${rendered}
 `)}else printResult(result,{...globalOptions,json:outputFormat==="json"});globalOptions.profile&&printError(`profile:command=context took_ms=${Date.now()-startedAt}`)}async function runNextAction(options,actionCommand){const globalOptions=getGlobalOptions(actionCommand),startedAt=Date.now(),nextOptions=normalizeNextOptions(applyContextIntentProjection("next",options)),result=await runNext(nextOptions,globalOptions),outputFormat=resolveNextOutputFormat(nextOptions,globalOptions);outputFormat==="markdown"?globalOptions.quiet||writeStdout(`${renderNextMarkdown(result)}
 `):printResult(result,{...globalOptions,json:outputFormat==="json"}),globalOptions.profile&&printError(`profile:command=next took_ms=${Date.now()-startedAt}`)}async function runSearchAction(keywords,options,command){const globalOptions=getGlobalOptions(command),startedAt=Date.now(),query=normalizeSearchKeywordsInput(keywords),intentOptions=applyContextIntentProjection("search",options,[query]),searchOptions=normalizeSearchOptions(intentOptions),result=await runSearch(query,searchOptions,globalOptions),outputFormat=typeof intentOptions.format=="string"?intentOptions.format.trim().toLowerCase():void 0,effectiveGlobal=resolveReadCommandOutputFormat("Search",intentOptions.format,globalOptions,!0);if(outputFormat==="ndjson"){setActiveCommandResult(result);const rendered=serializeNdjsonRows(result.items);!effectiveGlobal.quiet&&rendered.length>0&&writeStdout(`${rendered}