171 generated command pages

Reads or updates project/global settings such as definition-of-done, item format, telemetry, and policy toggles.

<scope>	Config scope: project|global, or action shorthand list|export|get|set for project scope
<action>	Config action: get|set|list|export
<key>	Config key for get|set; use `pm config project list` for the complete typed inventory, including mutation-guard-* policies
<value>	Optional value for set: routed to the right typed flag by key (e.g. config set telemetry-tracking off, config set item-format toon, config set definition-of-done "Tests pass"). Equivalent to --policy/--format/--criterion. context keys still require --default-depth/--section-* flags.

--criterion <text>	Criteria value for definition-of-done, metadata-required-fields, or lifecycle pattern keys (repeatable for set)
--clear-criteria	Clear criteria-list keys for config set operations
--format <value>	Item format for item-format key: toon
--policy <value>	Policy key values: history-missing-stream-policy=auto_create|strict_error; sprint-release-format-policy=warn|strict_error; parent-reference-policy=warn|strict_error; governance-preset=minimal|default|strict|custom; governance-ownership-enforcement=none|warn|strict; governance-create-mode-default=progressive|strict; governance-close-validation-default=off|warn|strict; governance-require-close-reason=enabled|disabled; governance-parent-reference-policy=warn|strict_error; governance-metadata-validation-profile=core|strict|custom; governance-force-required-for-stale-lock=enabled|disabled; governance-duplicate-detection-mode=off|advisory|strict; test-result-tracking=enabled|disabled; untrusted-linked-test-execution=enabled|disabled; telemetry-tracking=enabled|disabled
--value <value>	Typed nested setting value. Mutation guards: require-attributed-author=true|false, secret-guard=off|advise|block, stale-in-progress-hours=integer>=1. Kebab-case is preferred; underscore aliases remain accepted.
--default-depth <value>	Context default depth: brief|standard|deep
--activity-limit <n>	Context default activity limit
--stale-threshold-days <n>	Context staleness cutoff in days
--section-hierarchy <value>	Enable/disable context hierarchy section (true|false)
--section-activity <value>	Enable/disable context activity section (true|false)
--section-progress <value>	Enable/disable context progress section (true|false)
--section-blockers <value>	Enable/disable context blockers section (true|false)
--section-files <value>	Enable/disable context files section (true|false)
--section-workload <value>	Enable/disable context workload section (true|false)
--section-staleness <value>	Enable/disable context staleness section (true|false)
--section-tests <value>	Enable/disable context tests section (true|false)

Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.

--strict-directories	Treat optional item-type directories as required failures
--require-merge-drivers	Treat absent clone-local merge drivers as a required health failure
--check-only	Run read-only health diagnostics without refreshing vectors
--check-telemetry	Probe telemetry endpoint health and include network diagnostics
--no-refresh	Disable automatic vector refresh attempts during health checks
--refresh-vectors	Explicitly enable vector refresh attempts during health checks
--verbose-stale-items	Include full stale vectorization ID lists in health output
--verbose-author-events	Include every actionable unknown-author event coordinate for review or disposition
--brief	Emit compact health details for low-token agent checks
--summary	Emit one-line-style health status with check names and warning count
--skip-vectors	Skip vectorization check for a faster run
--skip-integrity	Skip item/history file integrity check for a faster run
--skip-drift	Skip history drift hash check for a faster run
--full	Run all checks including slow integrity, drift, and vectorization checks
--strict-exit	Return non-zero exit when health is not ok and default to actionable summary output; use --full for complete details

Bootstraps tracker storage and settings so all other commands can run safely.

<prefix-or-path>

Optional id prefix, or path-like tracker target such as ./pm-sandbox

--prefix, --id-prefix <value>	Set the item ID prefix (alias for the positional prefix)
--preset <value>	Governance preset for new setups: minimal|default|strict
--defaults	Use non-interactive setup defaults without opening the wizard
--author <value>	Set the default mutation author for this project
--agent-guidance <mode>	Agent guidance mode: ask|add|skip|status
--type-preset <name>	Register domain item types during init: agile|ops|research
--with-packages	Install all bundled first-party packages during initialization
--no-merge-fence	Skip automatic merge-driver installation for a fresh Git-backed tracker
--workspace <dir>	Initialize repository-local tracker storage at <dir>/.agents/pm
--force	Allow initializing tracker files directly in a directory that looks like a workspace root
--verbose	Include the full resolved settings tree in the output (default output is a concise summary)

Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.

<target>

Package source, name, or scaffold path

--init	Generate a starter package scaffold at target path
--capability <kind>	Starter capability for --init (default: commands)
--install	Install a package source
--dry-run	Resolve install sources and estimate copying without destination writes or activation
--uninstall	Uninstall an installed package
--explore	List discovered packages in selected scope
--manage	List managed packages with update-check metadata
--describe	Map every surface a loaded package registers (optionally one by name)
--markdown	Render describe output as a Markdown reference document (describe only)
--output <path>	Write describe Markdown to a file (requires --markdown)
--reload	Reload packages with cache-busted module imports
--watch	Use watch mode with --reload
--doctor	Run consolidated package diagnostics (summary/deep modes)
--catalog	List bundled first-party package catalog metadata
--adopt	Adopt an existing unmanaged package into managed metadata
--adopt-all	Adopt all unmanaged packages into managed metadata
--activate	Activate a package in selected scope settings
--deactivate	Deactivate a package in selected scope settings
--project	Use project package scope (default)
--global	Use global package scope
--gh <github-source>	Install from GitHub shorthand source (owner/repo[/path])
--ref <ref>	Git ref/branch/tag for GitHub install sources
--detail <mode>	Package diagnostics detail mode (summary|deep)
--trace	Include actionable registration traces in doctor deep diagnostics
--runtime-probe	Opt-in runtime activation probe for manage output parity
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--isolated	Run doctor against project-scope packages only, ignoring global registrations
--strict-exit	Return non-zero exit when doctor warnings are present (ok=false)
--declarative	Scaffold the composeExtension blueprint starter (any capability)

Installs, explores, manages, diagnoses, adopts, activates, deactivates, and refreshes package-backed pm runtime extensions.

<target>

Package source, name, or scaffold path

--init	Generate a starter package scaffold at target path
--capability <kind>	Starter capability for --init (default: commands)
--install	Install a package source
--dry-run	Resolve install sources and estimate copying without destination writes or activation
--uninstall	Uninstall an installed package
--explore	List discovered packages in selected scope
--manage	List managed packages with update-check metadata
--describe	Map every surface a loaded package registers (optionally one by name)
--markdown	Render describe output as a Markdown reference document (describe only)
--output <path>	Write describe Markdown to a file (requires --markdown)
--reload	Reload packages with cache-busted module imports
--watch	Use watch mode with --reload
--doctor	Run consolidated package diagnostics (summary/deep modes)
--catalog	List bundled first-party package catalog metadata
--adopt	Adopt an existing unmanaged package into managed metadata
--adopt-all	Adopt all unmanaged packages into managed metadata
--activate	Activate a package in selected scope settings
--deactivate	Deactivate a package in selected scope settings
--project	Use project package scope (default)
--global	Use global package scope
--gh <github-source>	Install from GitHub shorthand source (owner/repo[/path])
--ref <ref>	Git ref/branch/tag for GitHub install sources
--detail <mode>	Package diagnostics detail mode (summary|deep)
--trace	Include actionable registration traces in doctor deep diagnostics
--runtime-probe	Opt-in runtime activation probe for manage output parity
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--isolated	Run doctor against project-scope packages only, ignoring global registrations
--strict-exit	Return non-zero exit when doctor warnings are present (ok=false)
--declarative	Scaffold the composeExtension blueprint starter (any capability)

Provides deterministic project management workflows for humans and coding agents.

<subcommand> required	Required; schema verb (list/show, add/remove, rename/remap, policy-*), or custom type shorthand
<name>	Definition/source name or item id; policy-mode: advise|refuse

--definition <json>	Policy or proposed fields JSON
--policy <id>	Policy id for policy-approve
--message <text>	Audit rationale for a policy mutation
--description <text>	Type, status, or field description
--default-status <status>	Default status for this type
--folder <dir>	Storage folder for items of this custom type
--role <value>	Lifecycle role for a custom status (repeatable): draft, active, blocked, terminal, terminal_done, terminal_canceled, default_open, default_close, default_cancel
--order <n>	Display/sort order for a custom status
--type <type>	Value type for a custom field (add-field): string, number, boolean, string_array, array, object
--commands <list>	Field commands (repeatable/csv): create, update, update_many, list, search, calendar, context
--cli-flag <flag>	Override the auto-derived CLI flag for a custom field (add-field)
--required	Mark a custom field as always required (add-field)
--required-on-create	Mark a custom field as required at create time (add-field)
--no-allow-unset	Disallow clearing a custom field via --unset (add-field)
--required-types <list>	Restrict a custom field's requirement to specific item types (add-field; repeatable, comma-friendly)
--infer	Infer custom item types from title-prefix conventions (add-type; preview unless --apply)
--min-count <n>	Minimum items sharing a prefix for add-type --infer (default 10)
--apply	Register inferred types (add-type --infer); without it the command previews only
--to <name>	Target definition name for rename/remap migrations
--migration-id <id>	Stable idempotency key for a resumable schema migration
--dry-run	Preview schema changes without writes
--author <value>	Mutation author
--force	Force ownership/lock override

Runs grouped aggregation queries for governance checks such as decomposition by parent/type or triage by status/priority.

--set-mode <value>	Set grouping: element (default)|tuple
--limit <value>	Group page size (default: 50)
--after <value>	Continue with next_after cursor
--group-by <value>	Fields: parent,type,priority,status,assignee,tags,sprint,release (comma-separated)
--count	Counts (default)
--completion	Status counts and completion_pct
--sum <field>	Group numeric sum
--avg <field>	Group numeric average
--include-unparented	Keep unparented group
--status <value>	Item status
--type <value>	Item type
--tag <value>	Filter by tag
--priority <value>	Filter by priority
--deadline-before <value>	Latest deadline (ISO/date or relative)
--deadline-after <value>	Earliest deadline (ISO/date or relative)
--assignee <value>	Filter by assignee
--assignee-filter <value>	Assignee presence: assigned|unassigned
--parent <value>	Parent ID
--sprint <value>	Filter by sprint
--release <value>	Filter by release

Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.

--for <intent>	Apply a declared context intent projection. Allowed core values: handoff|orient. Configured package and workspace intents may extend this domain.
--date <value>	Anchor date/time for agenda window calculations (ISO/date string or relative)
--from <value>	Agenda lower bound (ISO/date string or relative)
--to <value>	Agenda upper bound (ISO/date string or relative)
--past	Include past agenda entries in bounded windows
--type <value>	Filter by item type
--tag <value>	Filter by tag
--priority <value>	Filter by priority
--assignee <value>	Filter by assignee
--assignee-filter <value>	Filter assignee presence: assigned|unassigned
--sprint <value>	Filter by sprint
--release <value>	Filter by release
--parent <id>	Scope the snapshot to one item's subtree (the item plus all descendants)
--limit <n>	Limit focus and agenda rows per section
--after <cursor>	Continue ranked focus after a next_cursor from a previous context response
--format <value>	Context output format override: markdown|toon|json|ndjson
--depth <value>	Context depth: brief|standard|deep|full (full = every section, no per-section cap)
--section <value...>	Include specific sections (repeatable; overrides --depth)
--fields <value>	Project focus rows to a comma-separated field subset (e.g. id,title,priority)
--activity-limit <n>	Limit recent activity entries (default: settings or 10)
--stale-threshold <value>	Staleness cutoff in days (e.g. 7 or 7d; default: settings or 7)
--explain-ranking	Include the scorer model, per-signal contributions, and ranked candidate ids
--token-budget <n>	Maximum estimated tokens spent on ranked focus rows
--no-extension-health	Omit the installed extension health summary
--no-tags	Omit tag arrays from context focus rows

Builds an agent-optimized snapshot of critical active work plus near-term agenda context with progressive depth levels.

--for <intent>	Apply a declared context intent projection. Allowed core values: handoff|orient. Configured package and workspace intents may extend this domain.
--date <value>	Anchor date/time for agenda window calculations (ISO/date string or relative)
--from <value>	Agenda lower bound (ISO/date string or relative)
--to <value>	Agenda upper bound (ISO/date string or relative)
--past	Include past agenda entries in bounded windows
--type <value>	Filter by item type
--tag <value>	Filter by tag
--priority <value>	Filter by priority
--assignee <value>	Filter by assignee
--assignee-filter <value>	Filter assignee presence: assigned|unassigned
--sprint <value>	Filter by sprint
--release <value>	Filter by release
--parent <id>	Scope the snapshot to one item's subtree (the item plus all descendants)
--limit <n>	Limit focus and agenda rows per section
--after <cursor>	Continue ranked focus after a next_cursor from a previous context response
--format <value>	Context output format override: markdown|toon|json|ndjson
--depth <value>	Context depth: brief|standard|deep|full (full = every section, no per-section cap)
--section <value...>	Include specific sections (repeatable; overrides --depth)
--fields <value>	Project focus rows to a comma-separated field subset (e.g. id,title,priority)
--activity-limit <n>	Limit recent activity entries (default: settings or 10)
--stale-threshold <value>	Staleness cutoff in days (e.g. 7 or 7d; default: settings or 7)
--explain-ranking	Include the scorer model, per-signal contributions, and ranked candidate ids
--token-budget <n>	Maximum estimated tokens spent on ranked focus rows
--no-extension-health	Omit the installed extension health summary
--no-tags	Omit tag arrays from context focus rows

Shows details for one item by ID, with optional lower-token projections for agent loops.

<id> required

Item id

--for <intent>	Apply a declared context intent projection. Allowed core values: inspect. Configured package and workspace intents may extend this domain.
--token-budget <n>	Override the selected intent's maximum estimated output tokens
--depth <value>	Detail depth: brief|standard|deep|full (full aliases deep; default: standard)
--full	Explicit full item read; equivalent to --depth deep (mutually exclusive with --depth/--fields)
--fields <value>	Render custom comma-separated item metadata fields. Allowed core values: acceptance_criteria|actual_result|affected_version|assignee|author|blocked_by|blocked_reason|body|children|claim_principal|claim_state|claim_state.assignee|claim_state.claimed|claim_state.last_claim|claim_state.last_release|close_reason|closed_at|collection_counts|comments|completed_at|component|confidence|created_at|customer_impact|deadline|definition_of_ready|dependencies|description|design|docs|duplicate_of|environment|estimated_minutes|events|expected_result|external_ref|files|fixed_version|goal|id|impact|learnings|linked|linked.docs|linked.files|linked.tests|notes|notes_count|objective|order|outcome|parent|plan_decisions|plan_discoveries|plan_harness|plan_mode|plan_resume_context|plan_scope|plan_steps|plan_validation|pm_format_version|priority|regression|release|reminders|reporter|repro_steps|resolution|reviewer|risk|schedule|schedule.deadline|schedule.end_at|schedule.events|schedule.location|schedule.reminders|schedule.start_at|severity|source_owner|source_type|sprint|status|tags|test_runs|tests|tests_count|title|type|type_options|unblock_note|updated_at|value|why_now. item.<field> aliases and configured runtime metadata fields are also accepted.
--tree	Include descendants rooted at the requested item
--tree-depth <n>	Maximum subtree depth for --tree descendants
--at <version-or-timestamp>	Reconstruct a verified historical item state without mutating it
--format <value>	Get output format override: json|toon

Lists active items with deterministic filtering and ordering.

--status <value>	Filter by status (repeatable or comma-separated; matches any; all selects every status)
--all	Include every lifecycle status
--for <intent>	Apply a declared context intent projection. Allowed core values: triage. Configured package and workspace intents may extend this domain.
--token-budget <n>	Override the selected intent's maximum estimated output tokens
--type <value>	Filter by item type (repeatable or comma-separated; matches any)
--tag <value>	Filter by tag (repeatable or comma-separated; matches any)
--priority <value>	Filter by priority (repeatable or comma-separated; matches any)
--deadline-before <value>	Filter by deadline upper bound (ISO/date string or relative)
--deadline-after <value>	Filter by deadline lower bound (ISO/date string or relative)
--today	Filter to items updated since local midnight today
--recent	Filter to items updated in the last 7 days
--updated-after <value>	Updated since ISO timestamp or signed relative (-2h/-7d for past); use last-window ISO
--updated-before <value>	Filter by updated_at upper bound: ISO timestamp or signed relative (-2h/+1d)
--created-after <value>	Filter by created_at lower bound: ISO timestamp or signed relative (-2h/+1d)
--created-before <value>	Filter by created_at upper bound: ISO timestamp or signed relative (-2h/+1d)
--ids <value>	Filter by explicit item IDs (comma-separated or repeatable)
--assignee <value>	Filter by assignee
--assignee-filter <value>	Filter assignee presence: assigned|unassigned
--parent <value>	Filter by parent item ID
--sprint <value>	Filter by sprint
--release <value>	Filter by release
--filter-ac-missing	Show only items missing acceptance_criteria
--filter-estimates-missing	Show only items missing estimated_minutes
--filter-resolution-missing	Show only terminal items missing resolution
--filter-metadata-missing	Show only items missing any tracked metadata (AC, estimate, or resolution)
--offset <n>	Skip the first n matching rows before limit is applied
--after <cursor>	Continue after an opaque next_cursor from a previous list response
--no-truncate	Return every matched row after the explicit status and field filters
--include-body	Include item body in each returned list row
--strict-read	Fail closed if any item document or item directory cannot be read
--compact	Render compact list projection fields (mutually exclusive with --brief/--full/--fields)
--brief	Ultra-compact output: id, status, type, title only (agent-optimized, mutually exclusive with --compact/--full/--fields)
--full	Render full list projection fields (mutually exclusive with --compact/--brief/--fields)
--fields <value>	Render custom comma-separated list fields (mutually exclusive with --compact/--brief/--full). Allowed core values: acceptance_criteria|actual_result|affected_version|assignee|author|blocked_by|blocked_reason|body|claim_principal|close_reason|closed_at|comments|completed_at|component|confidence|created_at|customer_impact|deadline|definition_of_ready|dependencies|description|design|docs|duplicate_of|environment|estimated_minutes|events|expected_result|external_ref|files|fixed_version|goal|id|impact|learnings|notes|objective|order|outcome|parent|plan_decisions|plan_discoveries|plan_harness|plan_mode|plan_resume_context|plan_scope|plan_steps|plan_validation|pm_format_version|priority|regression|release|reminders|reporter|repro_steps|resolution|reviewer|risk|severity|source_owner|source_type|sprint|status|tags|test_runs|tests|title|tree_children|tree_depth|tree_parent|tree_title|type|type_options|unblock_note|updated_at|value|why_now. item.<field> aliases and configured runtime metadata fields are also accepted.
--sort <value>	Sort field: priority|deadline|updated_at|created_at|title|parent (aliases: updated, created)
--order <value>	Sort order: asc|desc (requires --sort)
--tree	Render rows in parent/child tree order
--tree-depth <n>	Maximum recursion depth with --tree (0 keeps root rows only)
--format <value>	Output render mode: csv|table (human export) or json|ndjson|toon (machine output override)
--stream	Emit line-delimited JSON rows (requires --json)
--has-notes	Show only items that have notes
--has-learnings	Show only items that have learnings
--has-files	Show only items that have linked files
--has-docs	Show only items that have linked docs
--has-tests	Show only items that have linked tests
--has-comments	Show only items that have comments
--has-deps	Show only items that have dependencies
--has-body	Show only items that have a non-empty body
--has-linked-command	Show only items whose linked tests carry a runnable command
--no-notes	Show only items that have no notes
--no-learnings	Show only items that have no learnings
--no-files	Show only items that have no linked files
--no-docs	Show only items that have no linked docs
--no-tests	Show only items that have no linked tests
--no-comments	Show only items that have no comments
--no-deps	Show only items that have no dependencies
--empty-body	Show only items with an empty body
--no-linked-command	Show only items whose linked tests carry no runnable command
--filter-reviewer-missing	Show only items missing reviewer
--filter-risk-missing	Show only items missing risk
--filter-confidence-missing	Show only items missing confidence
--filter-sprint-missing	Show only items missing sprint
--filter-release-missing	Show only items missing release

Finds relevant items by keyword, semantic, or hybrid retrieval modes.

<keywords> required

Keyword query tokens

--for <intent>	Apply a declared context intent projection. Allowed core values: discover. Configured package and workspace intents may extend this domain.
--token-budget <n>	Override the selected intent's maximum estimated output tokens
--mode <value>	Search mode: keyword|semantic|hybrid (default: auto)
--semantic	Shorthand for --mode semantic
--hybrid	Shorthand for --mode hybrid
--match-mode <value>	Token match mode: and|or|exact (default: or with all-terms ranking bonus; and = hard-require every token; exact = exact phrase)
--min-score <value>	Per-query minimum score threshold (finite number >= 0); overrides settings search.score_threshold for this query only
--count	Return only the count of matching items (post-filter/threshold, pre-limit); skips hit rows
--semantic-weight <value>	Override hybrid semantic weight for this query (0..1); invalid values fall back to settings
--include-linked	Include linked files, docs, and tests in the searchable corpus
--title-exact	Require exact normalized title match for the full query string
--phrase-exact	Require exact normalized phrase match in searchable text
--highlight	Emit per-field matched-text snippets (wrapped in «…») on each hit; off by default
--status <value>	Filter by status before query (all, open/closed/canceled aliases, or configured status id; CSV)
--type <value>	Filter by item type
--tag <value>	Filter by tag
--priority <value>	Filter by priority
--deadline-before <value>	Filter by deadline upper bound (ISO/date string or relative)
--deadline-after <value>	Filter by deadline lower bound (ISO/date string or relative)
--updated-after <value>	Filter by updated_at lower bound: ISO timestamp or signed relative (e.g. "-2h"/"-7d" for the past)
--updated-before <value>	Filter by updated_at upper bound: ISO timestamp or signed relative (-2h/+1d)
--created-after <value>	Filter by created_at lower bound: ISO timestamp or signed relative (-2h/+1d)
--created-before <value>	Filter by created_at upper bound: ISO timestamp or signed relative (-2h/+1d)
--assignee <value>	Filter by assignee
--sprint <value>	Filter by sprint
--release <value>	Filter by release
--parent <value>	Filter by parent item ID
--compact	Render compact search hits (default; mutually exclusive with --full/--fields)
--full	Render full search hits with nested item payloads (mutually exclusive with --compact/--fields)
--fields <value>	Render custom comma-separated search hit fields (mutually exclusive with --compact/--full). Allowed core values: acceptance_criteria|actual_result|affected_version|assignee|author|blocked_by|blocked_reason|close_reason|comments|component|confidence|created_at|customer_impact|deadline|definition_of_ready|dependencies|description|docs|environment|estimated_minutes|events|expected_result|files|fixed_version|goal|highlights|id|impact|learnings|matched_fields|notes|objective|order|outcome|parent|plan|priority|rank|regression|release|reminders|reporter|repro_steps|resolution|reviewer|risk|score|severity|sprint|status|tags|tests|title|type|updated_at|value|why_now. item.<field> aliases and configured runtime metadata fields are also accepted.
--format <value>	Search output format override: json|ndjson|toon
--limit <n>	Limit returned item count
--after <cursor>	Continue after an opaque next_cursor from a previous search response
--has-notes	Show only items that have notes
--has-learnings	Show only items that have learnings
--has-files	Show only items that have linked files
--has-docs	Show only items that have linked docs
--has-tests	Show only items that have linked tests
--has-comments	Show only items that have comments
--has-deps	Show only items that have dependencies
--has-body	Show only items that have a non-empty body
--has-linked-command	Show only items whose linked tests carry a runnable command
--no-notes	Show only items that have no notes
--no-learnings	Show only items that have no learnings
--no-files	Show only items that have no linked files
--no-docs	Show only items that have no linked docs
--no-tests	Show only items that have no linked tests
--no-comments	Show only items that have no comments
--no-deps	Show only items that have no dependencies
--empty-body	Show only items with an empty body
--no-linked-command	Show only items whose linked tests carry no runnable command
--filter-reviewer-missing	Show only items missing reviewer
--filter-risk-missing	Show only items missing risk
--filter-confidence-missing	Show only items missing confidence
--filter-sprint-missing	Show only items missing sprint
--filter-release-missing	Show only items missing release

Adds implementation notes to body without replacing existing content.

<id> required	Item id
<text>	Body text; same as --body (- reads stdin)

--body <value>	Text to append to body (or - for stdin)
--author <value>	Mutation author
--message <value>	Mutation message
--force	Force ownership override

Claims an item to signal active ownership and reduce conflicts.

<id>	Item id (omit with --next)

--start	Claim and start an explicit item
--author <value>	Mutation author
--message <value>	History message
--force	Force claim override
--if-available	Skip another author's claim (skipped=true)
--next	Atomically claim the next caller-available actionable item
--type <value>	Filter --next candidates by type
--tag <value>	Filter --next candidates by tag
--priority <value>	Filter --next candidates by priority
--assignee-filter <value>	Filter --next candidates: assigned|unassigned
--parent <id>	Scope --next candidates to a subtree
--sprint <value>	Filter --next candidates by sprint
--release <value>	Filter --next candidates by release
--max-attempts <n>	Bound the --next candidate walk (default 10; maximum 100)
--include-decisions	Allow --next to claim human-gated Decision items
--include-gates	Allow --next to claim outcome gates
--include-containers	Allow --next to claim containers with unfinished descendants
--token-budget <n>	Bound the estimated tokens used to rank --next candidates
--explain-ranking	Include ranking provenance for --next selection

Transitions work to terminal closed state with explicit rationale.

<id> required	Item id
<text>	Close reason text (alias: --reason)

--release-assignment	Release ownership after closure
-r, --reason <value>	Close reason text (alias for positional <text>)
--close-reason <value>	Close reason text (alias for positional <text>)
--completed-at <value>	Actual completion timestamp (ISO or relative), distinct from tracker close time
-d, --duplicate-of <id>	Close as a duplicate of the canonical item id and auto-fill duplicate closure metadata
--author <value>	Mutation author
-m, --message <value>	History message
--validate-close [mode]	Validate closure metadata before close: "off", "warn", or "strict" (default: settings governance preset)
--resolution <value>	Closure resolution summary (checked by --validate-close strict)
--expected-result <value>	Expected outcome for closure validation
--expected <value>	Short alias for --expected-result
--actual-result <value>	Observed outcome for closure validation
--actual <value>	Short alias for --actual-result
--force	Force ownership override

Creates a new planning item with deterministic metadata and history.

<type-or-title>	Item title, or item type when a title follows (e.g. `pm create task "Fix bug"`)
<title>	Item title when the first argument is an item type

--title, -t <value> required	Item title [required] (or pass title as the first positional argument)
--id <value>	Explicit item id (normalized with the configured id_prefix)
--description, -d <value>	Item description (allow empty string)
--type <value>	Item type (built-ins plus any configured custom types)
--template <value>	Apply named create template defaults before explicit flags
--create-mode <value>	Create required-option policy mode: strict|progressive
--schedule-preset <value>	Scheduling preset for Reminder|Meeting|Event: lightweight
--status, -s <value>	Item status
--close-reason <value>	Close reason when creating directly in a terminal status
--completed-at <value>	Actual completion time for a terminal imported item
--priority, -p <value>	Priority 0..4
--tags <value>	Comma-separated tags
--add-tags <value>	Add tags additively on top of --tags (repeatable; CSV accepted)
--body, -b <value>	Item markdown body (allow empty string)
--deadline <value>	Deadline (ISO/date string or relative +6h/+1d/+2w/+6m)
--estimate, --estimated-minutes <value>	Estimated minutes
--acceptance-criteria <value>	Acceptance criteria (repeatable; values join with '; '; allow empty string)
--definition-of-ready <value>	Definition of ready (allow empty string)
--order <value>	Planning order/rank integer
--goal <value>	Goal identifier
--objective <value>	Objective identifier
--value <value>	Business value summary
--impact <value>	Business impact summary
--outcome <value>	Expected outcome summary
--why-now <value>	Why-now rationale
--author <value>	Mutation author
--message <value>	History message (allow empty string)
--assignee <value>	Item assignee
--parent <value>	Parent item ID
--allow-missing-parent	Allow creating with an unresolved parent reference and emit a validation warning
--allow-unresolved-deps	Allow unresolved local dependency targets and emit explicit warning receipts
--reviewer <value>	Reviewer
--risk <value>	Risk level: low|med|medium|high|critical (med persists as medium)
--confidence <value>	Confidence level: 0..100|low|med|medium|high (med persists as medium)
--sprint <value>	Sprint identifier
--release <value>	Release identifier
--blocked-by <value>	Set latest blocked-by item ID or reason; resolved item IDs append a blocked_by dependency edge
--blocked-reason <value>	Blocked reason
--unblock-note <value>	Unblock rationale note
--reporter <value>	Issue reporter
--severity <value>	Issue severity: low|med|medium|high|critical (med persists as medium)
--environment <value>	Issue environment context
--repro-steps <value>	Issue reproduction steps
--resolution <value>	Issue resolution summary
--expected-result <value>	Issue expected behavior
--expected <value>	Short alias for --expected-result
--actual-result <value>	Issue observed behavior
--actual <value>	Short alias for --actual-result
--affected-version <value>	Affected version identifier
--fixed-version <value>	Fixed version identifier
--component <value>	Issue component ownership
--regression [value]	Regression marker; bare flag means true, or pass true|false|1|0
--customer-impact <value>	Customer impact summary
--dep <value>	Seed dependency entry (key=value CSV, markdown key:value lines, or - for stdin; repeatable)
--type-option <value>	Type option key=value or key=<name>,value=<value> (also accepts key:value and markdown pairs; use - for stdin; repeatable)
--field <name=value>	Set a field declared by an active extension registerItemFields registration (repeatable)
--unset <field>	Clear scalar metadata field by name (repeatable)
--reminder <value>	Seed reminder entry at=<iso|relative>,text=<text> (also accepts markdown pairs and - for stdin; repeatable)
--event <value>	Seed event entry start=<iso|relative>,end=<iso|relative>,duration=<relative|30min|PT30M>,title=<text>,all_day=<true|false>,recur_* fields (also accepts markdown pairs and - for stdin; repeatable)
--comment <value>	Seed comment entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)
--note <value>	Seed note entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)
--learning <value>	Seed learning entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)
--file <value>	Seed linked file entry (CSV/markdown pairs or - for stdin; repeatable)
--test <value>	Seed linked test entry (CSV/markdown pairs or - for stdin; repeatable)
--doc <value>	Seed linked doc entry (CSV/markdown pairs or - for stdin; repeatable)
--stdin-json	Read a full item JSON document from stdin; explicit flags override document values
--body-file <path>	Load body from a file or stdin (-); conflicts with --body
--clear-deps	Clear dependency entries
--clear-comments	Clear comments
--clear-notes	Clear notes
--clear-learnings	Clear learnings
--clear-files	Clear linked files
--clear-tests	Clear linked tests
--clear-docs	Clear linked docs
--clear-reminders	Clear reminders
--clear-events	Clear events
--clear-type-options	Clear type options
--allow-duplicate	Explicitly create even when strict similarity governance finds likely duplicates

Removes an item while preserving history evidence and lock/ownership checks.

<id> required

Item id

--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override
--dry-run	Preview the item file that would be deleted without mutating

Releases an active claim when paused, handed off, or completed.

<id> required

Item id

--pause	Use open status
--author <value>	Author
--message <value>	Message
--force	Override ownership

Restores an item to a prior timestamp/version with history replay safety.

<id> required	Item id
<target> required	Restore target timestamp or version number

--author <value>	Mutation author
--message <value>	History message
--force	Force ownership/lock override

Mutates existing item fields while preserving history and lock safety.

<id> required

Item id

--title, -t <value>	Set title
--description, -d <value>	Set description
--body, -b <value>	Set body (allow empty string)
--status, -s <value>	Set status (use close command for closed)
--close-reason <value>	Set close reason
--priority, -p <value>	Set priority
--type <value>	Set type
--tags <value>	Set comma-separated tags (replaces existing). Use --add-tags / --remove-tags to mutate additively.
--add-tags <value>	Add tags to the existing list without replacing it (repeatable; CSV accepted)
--remove-tags <value>	Remove tags from the existing list (repeatable; CSV accepted)
--deadline <value>	Set deadline (ISO/date string or relative)
--estimate, --estimated-minutes <value>	Set estimated minutes
--acceptance-criteria <value>	Replace the complete acceptance-criteria list (repeatable values join with '; '); use --remove-ac plus --add-ac for one-entry repair
--add-ac <value>	Add one semicolon-free acceptance criterion without replacing the existing list (repeatable)
--remove-ac <value>	Remove one semicolon-free acceptance criterion by exact text match; fails if any selector is unmatched (repeatable)
--definition-of-ready <value>	Set definition of ready
--order <value>	Set planning order/rank integer
--goal <value>	Set goal identifier
--objective <value>	Set objective identifier
--value <value>	Set business value summary
--impact <value>	Set business impact summary
--outcome <value>	Set expected outcome summary
--why-now <value>	Set why-now rationale
--author <value>	Mutation author
--message <value>	Mutation message
--assignee <value>	Set assignee
--parent <value>	Set parent item ID
--allow-missing-parent	Allow updating to an unresolved parent reference and emit a validation warning
--allow-unresolved-deps	Allow unresolved local dependency targets and emit explicit warning receipts
--completed-at <value>	Correct the actual completion timestamp on a terminal item
--reviewer <value>	Set reviewer
--risk <value>	Set risk level: low|med|medium|high|critical (med persists as medium)
--confidence <value>	Set confidence level: 0..100|low|med|medium|high (med persists as medium)
--sprint <value>	Set sprint identifier
--release <value>	Set release identifier
--blocked-by <value>	Set latest blocked-by item ID or reason; resolved item IDs append a blocked_by dependency edge
--blocked-reason <value>	Set blocked reason
--unblock-note <value>	Set unblock rationale note
--reporter <value>	Set issue reporter
--severity <value>	Set issue severity: low|med|medium|high|critical (med persists as medium)
--environment <value>	Set issue environment context
--repro-steps <value>	Set issue reproduction steps
--resolution <value>	Set issue resolution summary
--expected-result <value>	Set issue expected behavior
--expected <value>	Short alias for --expected-result
--actual-result <value>	Set issue observed behavior
--actual <value>	Short alias for --actual-result
--affected-version <value>	Set affected version identifier
--fixed-version <value>	Set fixed version identifier
--component <value>	Set issue component ownership
--regression [value]	Set regression marker; bare flag means true, or pass true|false|1|0
--customer-impact <value>	Set customer impact summary
--dep <value>	Add dependency entries id=<id>,kind=<value>,author=<value>,created_at=<iso|now>,source_kind=<value> (repeatable)
--dep-remove <value>	Remove by dependency id or exact row signature (repeatable)
--comment <value>	Append comment seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)
--note <value>	Append note seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)
--learning <value>	Append learning seed author=<value>,created_at=<iso|now>,text=<value> (also accepts markdown pairs and - for stdin; repeatable)
--file <value>	Append linked file path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)
--test <value>	Append linked test command=<value>,path=<value>,scope=<project|global>,timeout_seconds=<n>,pm_context_mode=<schema|tracker|auto> (also accepts markdown pairs and - for stdin; repeatable)
--doc <value>	Append linked doc path=<value>,scope=<project|global>,note=<text> (also accepts markdown pairs and - for stdin; repeatable)
--reminder <value>	Set reminders at=<iso|relative>,text=<text> (also accepts markdown pairs and - for stdin; repeatable)
--event <value>	Set events start=<iso|relative>,end=<iso|relative>,duration=<relative|30min|PT30M>,title=<text>,all_day=<true|false>,recur_* fields (also accepts markdown pairs and - for stdin; repeatable)
--type-option <value>	Set type options key=value or key=<name>,value=<value> (also accepts key:value and markdown pairs; use - for stdin; repeatable)
--field <name=value>	Set a field declared by an active extension registerItemFields registration (repeatable)
--unset <field>	Clear scalar metadata field by name (repeatable)
--stdin-json	Read a full item JSON document from stdin; explicit flags override document values
--body-file <path>	Load body from a file or stdin (-); conflicts with --body
--replace-deps	Atomically replace dependency entries with the provided --dep values
--replace-tests	Atomically replace linked test entries with the provided --test values
--replace-files	Atomically replace linked file entries with the provided --file values
--replace-docs	Atomically replace linked doc entries with the provided --doc values
--clear-deps	Clear dependency entries
--clear-comments	Clear comments
--clear-notes	Clear notes
--clear-learnings	Clear learnings
--clear-files	Clear linked files
--clear-tests	Clear linked tests
--clear-docs	Clear linked docs
--clear-reminders	Clear reminders
--clear-events	Clear events
--clear-type-options	Clear type options
--force	Force ownership override

Bulk-updates matched item sets with dry-run previews and rollback checkpoints for safe large-scale metadata changes.

--filter-status <value>	Filter by status before applying updates
--filter-type <value>	Filter by item type before applying updates
--filter-tag <value>	Filter by tag before applying updates
--filter-priority <value>	Filter by priority before applying updates
--filter-deadline-before <value>	Filter by deadline upper bound before applying updates
--filter-deadline-after <value>	Filter by deadline lower bound before applying updates
--filter-updated-after <value>	Filter by updated_at lower bound before applying updates (ISO/relative)
--filter-updated-before <value>	Filter by updated_at upper bound before applying updates (ISO/relative)
--filter-created-after <value>	Filter by created_at lower bound before applying updates (ISO/relative)
--filter-created-before <value>	Filter by created_at upper bound before applying updates (ISO/relative)
--filter-assignee <value>	Filter by assignee before applying updates
--filter-assignee-filter <value>	Filter assignee presence: assigned|unassigned before applying updates
--filter-parent <value>	Filter by parent item ID before applying updates
--filter-sprint <value>	Filter by sprint before applying updates
--filter-release <value>	Filter by release before applying updates
--filter-ac-missing	Select only items missing acceptance_criteria (bulk backfill)
--filter-estimates-missing	Select only items missing estimated_minutes (bulk backfill)
--filter-resolution-missing	Select only terminal items missing resolution (bulk backfill)
--filter-metadata-missing	Select only items missing any tracked metadata (AC, estimate, or resolution)
--filter-has-notes	Select only items that have notes before applying updates
--filter-no-notes	Select only items that have no notes before applying updates
--filter-has-learnings	Select only items that have learnings before applying updates
--filter-no-learnings	Select only items that have no learnings before applying updates
--filter-has-files	Select only items that have linked files before applying updates
--filter-no-files	Select only items that have no linked files before applying updates
--filter-has-docs	Select only items that have linked docs before applying updates
--filter-no-docs	Select only items that have no linked docs before applying updates
--filter-has-tests	Select only items that have linked tests before applying updates
--filter-no-tests	Select only items that have no linked tests before applying updates
--filter-has-comments	Select only items that have comments before applying updates
--filter-no-comments	Select only items that have no comments before applying updates
--filter-has-deps	Select only items that have dependencies before applying updates
--filter-no-deps	Select only items that have no dependencies before applying updates
--filter-has-body	Select only items that have a non-empty body before applying updates
--filter-empty-body	Select only items with an empty body before applying updates
--filter-has-linked-command	Select only items whose linked tests carry a runnable command before applying updates
--filter-no-linked-command	Select only items whose linked tests carry no runnable command before applying updates
--filter-reviewer-missing	Select only items missing reviewer before applying updates
--filter-risk-missing	Select only items missing risk before applying updates
--filter-confidence-missing	Select only items missing confidence before applying updates
--filter-sprint-missing	Select only items missing sprint before applying updates
--filter-release-missing	Select only items missing release before applying updates
--ids <value>	Explicit ID allowlist: comma/newline text, - stdin, or @path file
--limit <n>	Limit matched item count before apply/preview
--offset <n>	Skip first n matched rows before apply/preview
--dry-run	Preview per-item diffs and checkpoint intent without mutating
--rollback <value>	Rollback a prior update-many checkpoint ID
--no-checkpoint	Disable checkpoint creation during apply mode
--title, -t <value>	Set title
--description, -d <value>	Set description
--body, -b <value>	Set body (allow empty string)
--status, -s <value>	Set status (use close command for closed)
--priority, -p <value>	Set priority
--type <value>	Set type
--tags <value>	Set comma-separated tags (replaces existing). Use --add-tags / --remove-tags to mutate additively.
--add-tags <value>	Add tags additively without replacing existing (repeatable; CSV accepted)
--remove-tags <value>	Remove tags from the existing list (repeatable; CSV accepted)
--deadline <value>	Set deadline (ISO/date string or relative)
--estimate, --estimated-minutes <value>	Set estimated minutes
--acceptance-criteria <value>	Set acceptance criteria
--add-ac <value>	Add one semicolon-free acceptance criterion without replacing the existing list (repeatable)
--remove-ac <value>	Remove one semicolon-free acceptance criterion by exact text match (repeatable)
--definition-of-ready <value>	Set definition of ready
--order <value>	Set planning order/rank integer
--goal <value>	Set goal identifier
--objective <value>	Set objective identifier
--value <value>	Set business value summary
--impact <value>	Set business impact summary
--outcome <value>	Set expected outcome summary
--why-now <value>	Set why-now rationale
--assignee <value>	Set assignee
--parent <value>	Set parent item ID
--reviewer <value>	Set reviewer
--risk <value>	Set risk level
--confidence <value>	Set confidence level
--sprint <value>	Set sprint identifier
--release <value>	Set release identifier
--blocked-by <value>	Set blocked-by item ID or reason
--blocked-reason <value>	Set blocked reason
--unblock-note <value>	Set unblock rationale note
--reporter <value>	Set issue reporter
--severity <value>	Set issue severity
--environment <value>	Set issue environment context
--repro-steps <value>	Set issue reproduction steps
--resolution <value>	Set issue resolution summary
--expected-result <value>	Set issue expected behavior
--expected <value>	Short alias for --expected-result
--actual-result <value>	Set issue observed behavior
--actual <value>	Short alias for --actual-result
--affected-version <value>	Set affected version identifier
--fixed-version <value>	Set fixed version identifier
--component <value>	Set issue component ownership
--regression [value]	Set regression marker; bare flag means true, or pass true|false|1|0
--customer-impact <value>	Set customer impact summary
--dep <value>	Add dependency entry id=<id>,kind=<kind>,author=<author>,created_at=<timestamp>
--dep-remove <value>	Remove dependency entries by id/kind/author/timestamp signature
--replace-deps	Atomically replace dependency entries with provided --dep values
--replace-tests	Atomically replace linked tests with provided --test values
--replace-files	Atomically replace linked files with provided --file values
--replace-docs	Atomically replace linked docs with provided --doc values
--comment <value>	Add comment seed author=<value>,created_at=<iso|now>,text=<value>
--note <value>	Add note seed author=<value>,created_at=<iso|now>,text=<value>
--learning <value>	Add learning seed author=<value>,created_at=<iso|now>,text=<value>
--file <value>	Add linked file path=<value>,scope=<project|global>,note=<text>
--test <value>	Add linked test command=<value>,path=<value>,scope=<project|global>
--doc <value>	Add linked doc path=<value>,scope=<project|global>,note=<text>
--reminder <value>	Add reminder entry at=<iso|relative>|date=<iso|relative>,text=<text>|title=<text>
--event <value>	Add event entry start=<iso|relative>,end=<iso|relative>,recur_*
--type-option <value>	Set type options key=value (repeatable)
--unset <field>	Clear scalar metadata field by name (repeatable)
--clear-deps	Clear dependency entries
--clear-comments	Clear comments
--clear-notes	Clear notes
--clear-learnings	Clear learnings
--clear-files	Clear linked files
--clear-tests	Clear linked tests
--clear-docs	Clear linked docs
--clear-reminders	Clear reminders
--clear-events	Clear events
--clear-type-options	Clear type options
--author <value>	Mutation author
--message <value>	Mutation message
--force	Force ownership override

Provides deterministic project management workflows for humans and coding agents.

<subcommand> required	Required; Plan subcommand: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize
<id>	Plan id (required for non-create subcommands); for create this may be the positional title
<step>	Step reference: stable id (plan-step-001) or order integer
<new-order>	New order integer for reorder-step

--title <value>	Plan title
--description <value>	Plan description
--scope <value>	Short scope statement of the target change or investigation
--parent <value>	Parent pm item id
--related <value>	Related pm item ids (repeatable, csv-friendly)
--blocks <value>	Pm item ids this plan blocks (repeatable, csv-friendly)
--blocked-by <value>	Pm item ids that block this plan (repeatable, csv-friendly)
--harness <value>	Plan harness provenance: codex|claude-code|cursor|generic
--mode <value>	Plan mode: draft|research|review|approved|executing|paused|completed|superseded
--resume-context <value>	Compact context summary for a future stateless agent
--tags <value>	Comma-separated tags
--priority <value>	Priority 0-4
--body <value>	Plan item body
--claim	Claim the plan on create for the author
--from-search <value>	Record the search query that led to plan creation
--template <value>	Seed plan steps from a built-in template: bug-investigation|feature-implementation|refactoring-sprint
--step-title <value>	Step title for add-step / update-step
--step <value>	Step title (repeatable on create: each --step appends an ordered step; elsewhere a single value aliases --step-title)
--step-body <value>	Step body text
--step-owner <value>	Step owner
--step-status <value>	Step status: pending|in_progress|completed|blocked|skipped|superseded
--step-evidence <value>	Step evidence text (used by update-step/complete-step)
--step-blocked-reason <value>	Step blocked reason (required when blocking)
--step-replacement <value>	Replacement reference for a superseded step
--depends-on <value>	Pm item ids the step depends on (repeatable, csv-friendly)
--link <value>	Pm item id to link (repeatable, csv-friendly)
--link-kind <value>	Link kind: related|blocks|blocked_by|depends_on|discovered_from|implements|recurs_from|verifies|supersedes
--link-note <value>	Optional note for the link
--promote-to-item-dep	Also add the linked id as a top-level item dependency when linking
--allow-multiple-active	Allow multiple steps to be in_progress at once
--file <value>	Step linked file path=<value>[,scope=project|global,note=<text>] (repeatable)
--test <value>	Step linked test command=<value>[,path=<value>,note=<text>] (repeatable)
--doc <value>	Step linked doc path=<value>[,scope=project|global,note=<text>] (repeatable)
--decision-text <value>	Decision log entry text
--decision-rationale <value>	Decision log entry rationale
--decision-evidence <value>	Decision log entry evidence
--discovery-text <value>	Discovery log entry text
--validation-text <value>	Validation log entry text
--validation-command <value>	Validation log entry command
--validation-expected <value>	Validation log entry expected outcome
--depth <value>	Show depth: brief|standard|deep (default: brief)
--fields <value>	Comma-separated field projection for show output
--steps <value>	Comma-separated step ids/orders for materialize
--materialize-type <value>	Item type for materialized steps (default: Task)
--materialize-parent <value>	Parent item id for materialized children (default: the plan)
--materialize-tags <value>	Comma-separated tags for materialized children
--field <name=value>	Custom field value forwarded to every materialized child (repeatable)
--author <value>	Mutation author
--message <value>	Mutation message
--force	Force ownership override
--create-mode <value>	Create required-option policy mode: strict|progressive
--status, -s <value>	Item status
--deadline <value>	Deadline (ISO/date string or relative +6h/+1d/+2w/+6m)
--estimate, --estimated-minutes <value>	Estimated minutes
--acceptance-criteria <value>	Acceptance criteria (repeatable; values join with '; '; allow empty string)
--definition-of-ready <value>	Definition of ready (allow empty string)
--order <value>	Planning order/rank integer
--goal <value>	Goal identifier
--objective <value>	Objective identifier
--value <value>	Business value summary
--impact <value>	Business impact summary
--outcome <value>	Expected outcome summary
--why-now <value>	Why-now rationale
--assignee <value>	Item assignee
--reviewer <value>	Reviewer
--risk <value>	Risk level: low|med|medium|high|critical (med persists as medium)
--confidence <value>	Confidence level: 0..100|low|med|medium|high (med persists as medium)
--sprint <value>	Sprint identifier
--release <value>	Release identifier
--blocked-reason <value>	Blocked reason
--unblock-note <value>	Unblock rationale note
--reporter <value>	Issue reporter
--severity <value>	Issue severity: low|med|medium|high|critical (med persists as medium)
--environment <value>	Issue environment context
--repro-steps <value>	Issue reproduction steps
--resolution <value>	Issue resolution summary
--expected-result <value>	Issue expected behavior
--expected <value>	Short alias for --expected-result
--actual-result <value>	Issue observed behavior
--actual <value>	Short alias for --actual-result
--affected-version <value>	Affected version identifier
--fixed-version <value>	Fixed version identifier
--component <value>	Issue component ownership
--regression [value]	Regression marker; bare flag means true, or pass true|false|1|0
--customer-impact <value>	Customer impact summary
--type-option <value>	Type option key=value or key=<name>,value=<value> (also accepts key:value and markdown pairs; use - for stdin; repeatable)
--reminder <value>	Seed reminder entry at=<iso|relative>,text=<text> (also accepts markdown pairs and - for stdin; repeatable)
--event <value>	Seed event entry start=<iso|relative>,end=<iso|relative>,duration=<relative|30min|PT30M>,title=<text>,all_day=<true|false>,recur_* fields (also accepts markdown pairs and - for stdin; repeatable)
--comment <value>	Seed comment entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)
--note <value>	Seed note entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)
--learning <value>	Seed learning entry (text=<value> CSV/markdown pairs or - for stdin; repeatable)

Adds or reviews lightweight status updates linked to an item.

<id> required	Item id
<text>	Optional comment text shorthand (equivalent to --add)

--add <text>	Append comment text; use text=<value> for structured input or - for stdin
--stdin	Read comment text from stdin (supports multiline markdown)
--file <path>	Read comment text from a file or stdin (-)
--edit <index>	Replace one comment using positional text, --add, --stdin, or --file
--delete <index>	Delete the comment at 1-based <index>
--limit <n>	Return only latest n comments
--full-history	Return complete comment history instead of a bounded mutation receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Comment author; defaults to PM_AUTHOR or settings
--message <value>	History message
--force	Force ownership override

Adds or reviews lightweight status updates linked to an item.

<id> required	Item id
<text>	Optional comment text shorthand (equivalent to --add)

--add <text>	Append comment text; use text=<value> for structured input or - for stdin
--stdin	Read comment text from stdin (supports multiline markdown)
--file <path>	Read comment text from a file or stdin (-)
--edit <index>	Replace one comment using positional text, --add, --stdin, or --file
--delete <index>	Delete the comment at 1-based <index>
--limit <n>	Return only latest n comments
--full-history	Return complete comment history instead of a bounded mutation receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Comment author; defaults to PM_AUTHOR or settings
--message <value>	History message
--force	Force ownership override

Adds or reviews post-implementation learnings for future work.

<id> required	Item id
<text>	Optional learning text shorthand for --add

--add <text>	Append learning text; use text=<value> or - for stdin
--stdin	Read learning text from stdin
--file <path>	Read learning text from a file or stdin (-)
--edit <index>	Replace one learning using positional text, --add, --stdin, or --file
--delete <index>	Delete the learning at 1-based <index>
--limit <n>	Return only latest n learnings
--full-history	Return complete learning history instead of a bounded receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Learning author (optional; falls back to PM_AUTHOR/settings)
--message <value>	History message
--force	Force ownership override

Adds or reviews durable implementation notes linked to an item.

<id> required	Item id
<text>	Optional note text shorthand for --add

--add <text>	Add a text note (- reads stdin)
--add-json <json>	Append a JSON event
--stdin	Read note text from stdin
--file <path>	Read note from file or stdin (-)
--edit <index>	Replace a 1-based note using the selected text input
--delete <index>	Delete the note at 1-based <index>
--limit <n>	Return only latest n notes
--since <timestamp>	Filter JSON events from this ISO time
--event-type <value>	Filter JSON events by top-level type
--include-meta	Include count and truncation metadata
--full-history	Return complete note history instead of a bounded receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Author; defaults to PM_AUTHOR/settings
--message <value>	History message
--force	Force ownership override

Adds or reviews post-implementation learnings for future work.

<id> required	Item id
<text>	Optional learning text shorthand for --add

--add <text>	Append learning text; use text=<value> or - for stdin
--stdin	Read learning text from stdin
--file <path>	Read learning text from a file or stdin (-)
--edit <index>	Replace one learning using positional text, --add, --stdin, or --file
--delete <index>	Delete the learning at 1-based <index>
--limit <n>	Return only latest n learnings
--full-history	Return complete learning history instead of a bounded receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Learning author (optional; falls back to PM_AUTHOR/settings)
--message <value>	History message
--force	Force ownership override

Adds or reviews durable implementation notes linked to an item.

<id> required	Item id
<text>	Optional note text shorthand for --add

--add <text>	Add a text note (- reads stdin)
--add-json <json>	Append a JSON event
--stdin	Read note text from stdin
--file <path>	Read note from file or stdin (-)
--edit <index>	Replace a 1-based note using the selected text input
--delete <index>	Delete the note at 1-based <index>
--limit <n>	Return only latest n notes
--since <timestamp>	Filter JSON events from this ISO time
--event-type <value>	Filter JSON events by top-level type
--include-meta	Include count and truncation metadata
--full-history	Return complete note history instead of a bounded receipt
--if-absent	Append only when resolved author and text are absent
--author [value]	Author; defaults to PM_AUTHOR/settings
--message <value>	History message
--force	Force ownership override

Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.

<id> required

Item id

--format <value>	Output format (tree, graph, or context)
--max-depth <value>	Maximum dependency traversal depth (0 keeps only the root)
--collapse <value>	Collapse mode (none or repeated)
--summary	Return counts only without full tree/graph payload
--full	Return the complete dependency row projection
--node-limit <value>	Maximum nodes in context output
--edge-limit <value>	Maximum edges and missing-reference rows in context output
--token-budget <value>	Maximum estimated tokens in context output
--cursor <value>	Continue an equivalent context query
--direction <value>	Context traversal direction (outgoing, incoming, or both)
--kind <value>	Restrict context traversal to registered relationship kinds (repeatable or comma-separated)

Associates relevant documentation paths with tracker items.

<id> required

Item id

--add <value>	Add linked doc entry (CSV/markdown pairs or - for stdin)
--add-glob <value>	Add linked doc entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)
--remove <value>	Remove linked doc by path only (path=<value>, path:<value>, plain path, or - for stdin); does not accept note=/scope= — record removal context with --message
--migrate <value>	Migrate linked doc paths in-place (from=<prefix>,to=<prefix>; repeatable)
--note <value>	Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)
--list	List linked docs without mutating
--validate-paths	Validate linked doc paths for existence and file shape
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Associates changed source files with tracker items for reproducibility.

<id> required

Item id

--add <value>	Add linked file entry (CSV/markdown pairs or - for stdin)
--add-glob <value>	Add linked file entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)
--remove <value>	Remove linked file by path only (path=<value>, path:<value>, plain path, or - for stdin); does not accept note=/scope= — record removal context with --message
--migrate <value>	Migrate linked file paths in-place (from=<prefix>,to=<prefix>; repeatable)
--note <value>	Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)
--list	List linked files without mutating
--append-stable	Preserve existing linked-file order and append new links without full-array resorting
--validate-paths	Validate linked file paths for existence and file shape
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.

--dry-run	Preview cleanup targets without deleting files; without this flag, pm gc deletes matched artifacts
--scope <value>	Limit cleanup to one or more scopes (comma-separated or repeatable): index, embeddings, runtime, locks, checkpoints, transactions

Links test commands/paths and optionally executes them for one item.

<id> required

Item id

--add <value>	Add verified isolated test (CSV/markdown or stdin)
--add-json <value>	Add verified isolated test (JSON object/array or stdin)
--remove <value>	Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)
--remove-index <n>	Remove the 1-based linked-test index from --list order (repeatable)
--list	List linked tests without mutating
--run	Run linked test commands
--match <value>	Run only linked tests whose command/path contains this substring
--only-index <n>	Run only the 1-based linked-test index from --list order
--only-last	Run only the most recently added linked test
--acknowledge-linked-tests	Trust the item's current linked commands in this clone without executing them
--background	Run linked tests in managed background mode
--timeout <seconds>	Default run timeout in seconds
--progress	Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)
--env-set <value>	Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)
--env-clear <value>	Clear environment variable(s) for linked-test runs (NAME, repeatable)
--shared-host-safe	Apply additive shared-host-safe runtime defaults for linked-test runs
--pm-context <mode>	PM linked-test context mode: schema|tracker|auto (default: schema)
--override-linked-pm-context	Force run-level --pm-context to override per-linked-test pm_context_mode metadata
--workspace-context <mode>	Source-workspace mode: source|isolated|snapshot (default: source)
--override-linked-workspace-context	Force run-level --workspace-context over per-linked-test metadata
--allow-untrusted-linked-tests	Execute untrusted linked commands when project policy also permits it
--fail-on-context-mismatch	Fail linked PM commands when context item counts differ
--fail-on-skipped	Treat skipped linked tests as dependency failures
--fail-on-empty-test-run	Treat successful linked-test commands that report zero executed tests as failures
--require-assertions-for-pm	Require assertion metadata for linked PM command tests
--check-context	Preflight linked PM command context diagnostics before executing commands
--auto-pm-context	Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context
--measure <value>	Record name=value[,unit=...][,threshold=...] evidence; repeatable
--metric-below <value>	Return evidence below name=value
--metric-diff <name>	Diff the latest two values
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Runs linked tests in bulk for release/readiness sweeps.

--status <value>	Filter items by status before running tests
--limit <n>	Limit matching items before running linked tests
--offset <n>	Skip matching items before running linked tests
--background	Run linked tests in managed background mode
--timeout <seconds>	Default run timeout in seconds
--progress	Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)
--env-set <value>	Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)
--env-clear <value>	Clear environment variable(s) for linked-test runs (NAME, repeatable)
--shared-host-safe	Apply additive shared-host-safe runtime defaults for linked-test runs
--pm-context <mode>	PM linked-test context mode: schema|tracker|auto (default: schema)
--override-linked-pm-context	Force run-level --pm-context to override per-linked-test pm_context_mode metadata
--workspace-context <mode>	Source-workspace mode: source|isolated|snapshot (default: source)
--override-linked-workspace-context	Force run-level --workspace-context over per-linked-test metadata
--allow-untrusted-linked-tests	Execute untrusted linked commands when project policy also permits it
--fail-on-context-mismatch	Fail linked PM commands when context item counts differ
--fail-on-skipped	Treat skipped linked tests as dependency failures
--fail-on-empty-test-run	Treat successful linked-test commands that report zero executed tests as failures
--require-assertions-for-pm	Require assertion metadata for linked PM command tests
--check-context	Preflight linked PM command context diagnostics before executing commands
--auto-pm-context	Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context

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.

--check-metadata	Run metadata completeness checks
--metadata-profile <value>	Metadata profile (core|strict|custom)
--check-resolution	Run closed-item resolution metadata checks
--check-completeness	Check declarative lifecycle field requirements
--check-lifecycle	Run active-item lifecycle governance drift checks
--check-stale-blockers	Include stale blocker-pattern diagnostics in lifecycle checks
--dependency-cycle-severity <value>	Set dependency-cycle warning policy for lifecycle checks (off|warn|error)
--parent-cycle-severity <value>	Set parent-hierarchy cycle warning policy for lifecycle checks (off|warn|error)
--check-files	Run linked-file and orphaned-file checks
--check-command-references	Run linked-command PM-ID reference checks
--scan-mode <value>	Select file candidate scan mode for --check-files (default|tracked-all|tracked-all-strict)
--include-pm-internals	Include PM storage internals in tracked-all candidate scans
--verbose-file-lists	Include full file-path lists for validate --check-files details
--verbose-diagnostics	Include full diagnostic ID lists
--all-affected-ids	Emit complete missing_* affected-ID lists with no truncation (implied by --json)
--strict-exit	Return non-zero exit when validation warnings are present
--fix-hints	Add a machine-executable fix_hints[] of pm commands to each failing check's details
--auto-fix	Apply safe, deterministic field backfills
--dry-run	Preview planned --auto-fix/--prune-missing fixes without applying them
--fix-scope <scope>	Grant --auto-fix scopes (metadata, resolution, estimates, timestamps, lifecycle; comma-separated or repeatable). Default: metadata, resolution; other scopes require explicit opt-in
--prune-missing	Remove deleted-path file/doc links; preserves real files
--check-history-drift	Run item/history hash drift checks
--check-storage-integrity	Run the post-merge storage-integrity check (unreadable items, history conflict markers, resurrected deletes, unparseable config/schema)
--counts	Keep validation counts and totals while omitting per-item diagnostic arrays
--full	Return the complete validation diagnostic projection

Reviews recent tracker-wide activity across items.

--id <value>	Filter by item ID
--op <value>	Filter by history operation
--author <value>	Filter by history author
--from <value>	Lower timestamp bound (ISO/date string or relative)
--to <value>	Upper timestamp bound (ISO/date string or relative)
--limit <n>	Return only the latest n activity entries
--unbounded	Explicitly return every matching activity entry (disables the default bound)
--compact	Condensed output: show only id, op, ts, author, msg per entry
--raw	Show the legacy compact per-event stream instead of the item digest
--full	Show full activity entries with JSON Patch payloads
--provenance	Show patch-free author, harness, instance, and extensible provenance
--provenance-summary	Include bounded provenance completeness counts
--harness <value>	Filter by recorded or vocabulary-resolved harness (repeatable)
--agent-instance <value>	Filter by privacy-safe agent instance (repeatable)
--provenance-filter <dimension=value>	Filter by an exact declared provenance value (repeatable)
--stream [mode]	Emit line-delimited JSON rows (requires --json). Optional mode: rows|ndjson|jsonl

Inspects item mutation timeline and audit trail.

<id> required

Item id

--limit <n>	Latest n entries
--compact	Index, time, op, author, patch count, fields
--full	Full entries with JSON Patches
--provenance	Authors and provenance; no patches
--provenance-summary	Count provenance completeness
--harness <value>	Recorded/resolved harness (repeatable)
--agent-instance <value>	Agent instance (repeatable)
--provenance-filter <dimension=value>	Exact provenance match (repeatable)
--diff	Before/after field diffs
--field <name>	Filter changed field; implies --diff
--verify	Verify full chain and replay
--strict-exit	With --verify, fail on integrity errors
--format <value>	Output: json|toon

Reports tracker-level totals and distribution by type/status.

--include-empty	Restore zero-count registered item-type and lifecycle-status buckets
--storage	Include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries)
--metadata-coverage	Include metadata coverage % (acceptance_criteria, estimated_minutes, resolution, tags, parent) overall and by type
--by-assignee	Include a lifecycle-bucketed item breakdown grouped by assignee
--by-tag	Include a lifecycle-bucketed item breakdown grouped by tag
--by-priority	Include a lifecycle-bucketed item breakdown grouped by priority
--tag-prefix <value>	With --by-tag: only count tags starting with this prefix (e.g. domain:)
--field-utilization	Report content-field utilization rates (notes/learnings/files/docs/tests/comments/deps/body) for governance analysis
--analytics <json>	Improvement ledger/history analytics JSON

Exposes machine-readable CLI command and tool schema contracts for agent integrations.

--action <value>	Filter tool schema branches to a specific action
--command <value>	Scope contracts output to one CLI command (narrow-by-default)
--summary	Return one command+intent row per top-level command for cheap agent bootstrap
--schema-only	Return schema-focused output only
--flags-only	Return command flag contracts only
--availability-only	Return action availability surface only
--runtime-only	Include only actions invocable in the current runtime
--full	Include full schema and command-flag surfaces (large; default brief output omits heavy sections for unfiltered queries)

Provides deterministic project management workflows for humans and coding agents.

<action> required	Action; inspect `pm contracts --command assurance`
<kind>	Declaration kind or run gate id
<id>	Declaration/gate id

--definition <json>	Put declaration JSON
--trigger <value>	Gate trigger
--tree <value>	Revision identity
--gate <id>	Verdict gate filter
--limit <number>	Verdict limit
--dry-run	Evaluate without recording
--author <value>	Mutation author
--message <value>	Mutation rationale
--owner <item-id>	Preset/derivation owner
--apply	Persist derived proposals
--enforcement <level>	Promote to warn or block

Apply one assurance adoption preset.

<preset> required

string value.

--author <value>	Mutation author
--message <value>	Mutation rationale
--owner <item-id>	Preset/derivation owner

Derive assurance proposals from current project context.

--author <value>	Mutation author
--message <value>	Mutation rationale
--owner <item-id>	Preset/derivation owner
--apply	Persist derived proposals

Measure all recorded recurrence lineages with bounded evidence rows.

--definition <json>

Put declaration JSON

List assurance declarations by kind.

<kind> required

string value.

List available assurance adoption presets.

<preset>

string value.

--author <value>	Mutation author
--message <value>	Mutation rationale
--owner <item-id>	Preset/derivation owner

Promote one assertion into a warning or blocking gate.

<assertion-id> required

string value.

--author <value>	Mutation author
--message <value>	Mutation rationale
--enforcement <level>	Promote to warn or block

Put assurance declarations by kind.

<kind> required	string value.
<id> required	string value.

--definition <json>	Put declaration JSON
--author <value>	Mutation author
--message <value>	Mutation rationale

Remove assurance declarations by kind.

<kind> required	string value.
<id> required	string value.

--author <value>	Mutation author
--message <value>	Mutation rationale

Analyze bounded defect-recurrence risk for a proposed change.

--definition <json>

Put declaration JSON

Evaluate one assurance gate for a lifecycle trigger.

<gate-id> required

string value.

--trigger <value>	Gate trigger
--tree <value>	Revision identity
--dry-run	Evaluate without recording

Show assurance declarations by kind.

<kind> required	string value.
<id> required	string value.

List bounded assurance verdict history.

<gate-id>

string value.

--gate <id>	Verdict gate filter
--limit <number>	Verdict limit

Removes an item while preserving history evidence and lock/ownership checks.

<id> required

Item id

--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override
--dry-run	Preview the item file that would be deleted without mutating

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 — unlike update-many --status closed, which bypasses close validation.

--filter-status <value>	Filter by status before closing
--filter-type <value>	Filter by item type before closing
--filter-tag <value>	Filter by tag before closing
--filter-priority <value>	Filter by priority before closing
--filter-deadline-before <value>	Filter by deadline upper bound before closing
--filter-deadline-after <value>	Filter by deadline lower bound before closing
--filter-updated-after <value>	Filter by updated_at lower bound before closing (ISO/relative)
--filter-updated-before <value>	Filter by updated_at upper bound before closing (ISO/relative)
--filter-created-after <value>	Filter by created_at lower bound before closing (ISO/relative)
--filter-created-before <value>	Filter by created_at upper bound before closing (ISO/relative)
--filter-assignee <value>	Filter by assignee before closing
--filter-assignee-filter <value>	Filter assignee presence: assigned|unassigned before closing
--filter-parent <value>	Filter by parent item ID before closing
--filter-sprint <value>	Filter by sprint before closing
--filter-release <value>	Filter by release before closing
--filter-has-notes	Select only items that have notes before closing
--filter-no-notes	Select only items that have no notes before closing
--filter-has-learnings	Select only items that have learnings before closing
--filter-no-learnings	Select only items that have no learnings before closing
--filter-has-files	Select only items that have linked files before closing
--filter-no-files	Select only items that have no linked files before closing
--filter-has-docs	Select only items that have linked docs before closing
--filter-no-docs	Select only items that have no linked docs before closing
--filter-has-tests	Select only items that have linked tests before closing
--filter-no-tests	Select only items that have no linked tests before closing
--filter-has-comments	Select only items that have comments before closing
--filter-no-comments	Select only items that have no comments before closing
--filter-has-deps	Select only items that have dependencies before closing
--filter-no-deps	Select only items that have no dependencies before closing
--filter-has-body	Select only items that have a non-empty body before closing
--filter-empty-body	Select only items with an empty body before closing
--filter-has-linked-command	Select only items whose linked tests carry a runnable command before closing
--filter-no-linked-command	Select only items whose linked tests carry no runnable command before closing
--filter-reviewer-missing	Select only items missing reviewer before closing
--filter-risk-missing	Select only items missing risk before closing
--filter-confidence-missing	Select only items missing confidence before closing
--filter-sprint-missing	Select only items missing sprint before closing
--filter-release-missing	Select only items missing release before closing
--ids <value>	Explicit ID allowlist: comma/newline text, - stdin, or @path file
--limit <n>	Limit matched item count before apply/preview
--offset <n>	Skip first n matched rows before apply/preview
--reason <value>	Shared close reason applied to matched items (required when governance.require_close_reason is enabled)
--completed-at <value>	Actual completion timestamp (ISO or relative) applied to every matched item
--resolution <value>	Shared closure resolution applied to every matched item (closure-validation field)
--expected-result <value>	Shared expected-result note (closure-validation field)
--expected <value>	Short alias for --expected-result
--actual-result <value>	Shared actual-result note (closure-validation field)
--actual <value>	Short alias for --actual-result
--validate-close [mode]	Validate closure metadata per item: "off", "warn", or "strict" (default: settings governance preset)
--author <value>	Mutation author
--message <value>	History message
--force	Re-close already-terminal matches and override ownership
--dry-run	Preview matched items + per-item skip/active-child plan without mutating
--rollback <value>	Rollback a prior close-many checkpoint ID
--no-checkpoint	Disable checkpoint creation during apply mode

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 — unlike update-many --status closed, which bypasses close validation.

--filter-status <value>	Filter by status before closing
--filter-type <value>	Filter by item type before closing
--filter-tag <value>	Filter by tag before closing
--filter-priority <value>	Filter by priority before closing
--filter-deadline-before <value>	Filter by deadline upper bound before closing
--filter-deadline-after <value>	Filter by deadline lower bound before closing
--filter-updated-after <value>	Filter by updated_at lower bound before closing (ISO/relative)
--filter-updated-before <value>	Filter by updated_at upper bound before closing (ISO/relative)
--filter-created-after <value>	Filter by created_at lower bound before closing (ISO/relative)
--filter-created-before <value>	Filter by created_at upper bound before closing (ISO/relative)
--filter-assignee <value>	Filter by assignee before closing
--filter-assignee-filter <value>	Filter assignee presence: assigned|unassigned before closing
--filter-parent <value>	Filter by parent item ID before closing
--filter-sprint <value>	Filter by sprint before closing
--filter-release <value>	Filter by release before closing
--filter-has-notes	Select only items that have notes before closing
--filter-no-notes	Select only items that have no notes before closing
--filter-has-learnings	Select only items that have learnings before closing
--filter-no-learnings	Select only items that have no learnings before closing
--filter-has-files	Select only items that have linked files before closing
--filter-no-files	Select only items that have no linked files before closing
--filter-has-docs	Select only items that have linked docs before closing
--filter-no-docs	Select only items that have no linked docs before closing
--filter-has-tests	Select only items that have linked tests before closing
--filter-no-tests	Select only items that have no linked tests before closing
--filter-has-comments	Select only items that have comments before closing
--filter-no-comments	Select only items that have no comments before closing
--filter-has-deps	Select only items that have dependencies before closing
--filter-no-deps	Select only items that have no dependencies before closing
--filter-has-body	Select only items that have a non-empty body before closing
--filter-empty-body	Select only items with an empty body before closing
--filter-has-linked-command	Select only items whose linked tests carry a runnable command before closing
--filter-no-linked-command	Select only items whose linked tests carry no runnable command before closing
--filter-reviewer-missing	Select only items missing reviewer before closing
--filter-risk-missing	Select only items missing risk before closing
--filter-confidence-missing	Select only items missing confidence before closing
--filter-sprint-missing	Select only items missing sprint before closing
--filter-release-missing	Select only items missing release before closing
--ids <value>	Explicit ID allowlist: comma/newline text, - stdin, or @path file
--limit <n>	Limit matched item count before apply/preview
--offset <n>	Skip first n matched rows before apply/preview
--reason <value>	Shared close reason applied to matched items (required when governance.require_close_reason is enabled)
--completed-at <value>	Actual completion timestamp (ISO or relative) applied to every matched item
--resolution <value>	Shared closure resolution applied to every matched item (closure-validation field)
--expected-result <value>	Shared expected-result note (closure-validation field)
--expected <value>	Short alias for --expected-result
--actual-result <value>	Shared actual-result note (closure-validation field)
--actual <value>	Short alias for --actual-result
--validate-close [mode]	Validate closure metadata per item: "off", "warn", or "strict" (default: settings governance preset)
--author <value>	Mutation author
--message <value>	History message
--force	Re-close already-terminal matches and override ownership
--dry-run	Preview matched items + per-item skip/active-child plan without mutating
--rollback <value>	Rollback a prior close-many checkpoint ID
--no-checkpoint	Disable checkpoint creation during apply mode

Sets a session focused item so new pm create items default their --parent to it (project management = context management).

<id>	Item id to focus (omit to show current focus)

--clear

Clear the focused item

Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.

--for <intent>	Apply a declared context intent projection. Allowed core values: execute. Configured package and workspace intents may extend this domain.
--type <value>	Filter candidate items by type
--tag <value>	Filter candidate items by tag
--priority <value>	Filter candidate items by priority
--assignee <value>	Filter candidate items by assignee
--assignee-filter <value>	Filter assignee presence: assigned|unassigned
--sprint <value>	Filter candidate items by sprint
--release <value>	Filter candidate items by release
--parent <id>	Scope to one item's subtree (the item plus all descendants)
--limit <n>	Limit ready rows (default: 5; non-positive falls back to default)
--blocked-limit <n>	Limit blocked rows (default: same as --limit)
--ready-only	Omit the blocked companion list
--include-decisions	Include human-gated Decision items in the claimable ready queue
--include-gates	Include outcome gates in the ready queue
--include-containers	Include containers with unfinished descendants in the ready queue
--format <value>	Next output format override: markdown|toon|json
--explain-ranking	Include the scorer model, per-signal contributions, and ranked ready ids
--token-budget <n>	Maximum estimated tokens spent on the ranked ready queue

Provides deterministic project management workflows for humans and coding agents.

<id> required

Source item id

--title <value>	Optional title override for the copied item
--author <value>	Mutation author
--message <value>	History message
--allow-duplicate	Explicitly copy even when strict similarity governance finds likely duplicates

Provides deterministic project management workflows for humans and coding agents.

--status <value>	Statuses (repeatable or comma-separated)
--since <value>	Created at or after this time
--threshold <value>	Minimum similarity (0-1)
--limit <n>	Maximum clusters
--exhaustive	Score all pairs within the safety bound

Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.

--mode <value>	Default retrieval mode for queries without their own: keyword|semantic|hybrid (default: keyword)
--k <n>	Metric cutoff @k (positive integer; default: 10)
--fail-under <value>	Exit non-zero when aggregate nDCG@k falls below this threshold (0..1); CI gate
--queries <path>	Query JSON (https://schema.unbrained.dev/pm/eval-query-set/v1); default: search/eval-queries.json; errors show an example
--format <value>	Eval output format override: json|toon

Provides deterministic project management workflows for humans and coding agents.

--since <cursor-or-timestamp>	Resume strictly after a durable cursor, or include events from an ISO timestamp
--type <value>	Filter by mutation operation (repeatable or comma-separated)
--author <value>	Filter by mutation author (repeatable or comma-separated)
--item <value>	Filter by item or workspace stream id (repeatable or comma-separated)
--limit <n>	Return at most 1,000 events (default: 100)
--cursor-mode <mode>	Cursor framing: batch emits one terminal trailer (default); row preserves one cursor per event
--full	Include each complete authoritative history entry
--provenance	Include patch-free author, harness, instance, and extensible provenance
--provenance-summary	Include bounded provenance completeness counts
--harness <value>	Filter by recorded or vocabulary-resolved harness (repeatable)
--agent-instance <value>	Filter by privacy-safe agent instance (repeatable)
--provenance-filter <dimension=value>	Filter by an exact declared provenance value (repeatable)
--follow	Continue emitting committed events as newline-delimited JSON
--interval-ms <n>	Empty-read delay while following (minimum: 10ms; default: 250ms)

Provides deterministic project management workflows for humans and coding agents.

<target> required

Extension name

--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Extension name

--gh <owner/repo[/path]>	GitHub provenance shorthand for adopted extension
--ref <ref>	Git ref/branch/tag for GitHub shorthand source
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project extension scope (default)
--global	Use global extension scope

Compatibility view of bundled package catalog metadata.

--fields <value>	Render compact comma-separated catalog fields, for example: alias,installed,install_command
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Extension name

--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

<target>

Extension name to describe (omit for every loaded extension)

--markdown	Render the surface map as a Markdown reference document instead of toon/json
--output <path>	Write Markdown output to a file (requires --markdown)
--project	Use project extension scope (default)
--global	Use global extension scope

Diagnoses compatibility extension activation, policy, collision, and managed-state health for project or global extension scopes.

--detail <mode>	Detail mode for extension diagnostics (summary|deep)
--trace	Include actionable registration traces in doctor deep diagnostics
--fix-managed-state	Adopt unmanaged extensions before diagnostics/update checks
--isolated	Run doctor against project-scope extensions only, ignoring global registrations
--strict-exit	Return non-zero exit when doctor warnings are present (ok=false)
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project extension scope (default)
--global	Use global extension scope

Generates an installable starter runtime extension with manifest and entrypoint files.

<target> required

Scaffold target directory path

--capability <kind>	Capability the starter targets (commands|hooks|search|importers|schema|profile|renderers|parser|preflight|services; default commands)
--project	Use project extension scope (default)
--global	Use global extension scope

Installs a compatibility runtime extension from local, npm, GitHub, bundled alias, or wildcard sources.

<targets>

Extension source (local path, bundled alias, npm: source, wildcard, or GitHub source)

--dry-run	Resolve sources and estimate copying without destination writes or activation
--gh <github-source>	Install from GitHub shorthand source (owner/repo[/path])
--ref <ref>	Git ref/branch/tag for GitHub install sources
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

--runtime-probe	Opt-in runtime activation probe for manage output parity
--fix-managed-state	Adopt unmanaged extensions before diagnostics/update checks
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

--dry-run	Plan active migrations without invoking extension code
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

--watch	Use watch mode for repeated reload checks
--project	Use project extension scope (default)
--global	Use global extension scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Extension name

--project	Use project extension scope (default)
--global	Use global extension scope

Sets a session focused item so new pm create items default their --parent to it (project management = context management).

<id>	Item id to focus (omit to show current focus)

--clear

Clear the focused item

Provides deterministic project management workflows for humans and coding agents.

<subcommand> required	Graph query (ancestors, descendants, predecessors, successors, paths, impact, analyze, audit, communities, redundancy, dominators, slack, centrality, articulation, plan, index)
<id>	Root item id (traversals, paths, impact, and dominators)
<target>	Target item id (paths only)

--kind <value>	Restrict traversal to registered relationship kinds (repeatable or comma-separated)
--max-depth <value>	Maximum traversal depth (non-negative integer)
--limit <value>	Maximum returned rows per bounded collection
--after <value>	Resume a traversal after this previously returned node id
--direction <value>	Edge orientation for paths/impact (outgoing, incoming, or both)
--max-paths <value>	Maximum enumerated paths (paths only)
--sample <value>	Maximum evidence sample entries per audit finding (audit only)
--exempt-isolate <value>	Item ids treated as explicitly valid isolates by the audit (repeatable or comma-separated)
--exempt-isolate-type <value>	Item types whose active isolates are policy-valid for the audit (repeatable or comma-separated)
--save-baseline	Persist the audit census as the change-since-baseline comparison point (audit only)
--rebuild	Rebuild and warm the durable graph index (index only)
--clear	Delete the durable graph index (index only)
--summary	Return counts-first envelopes without row collections
--full	Return the complete graph row projection

Provides deterministic project management workflows for humans and coding agents.

--event <item-id:line>	Unknown-author event coordinate (repeatable)
--all-actionable	Select all actionable events
--dry-run	Preview a deterministic source-bound plan
--plan-fingerprint <sha256>	Apply the exact fingerprint returned by --dry-run
--limit <n>	Maximum coordinate rows returned in the plan
--attributed-author <value>	Reviewed principal attribution
--reviewer <value>	Disposition reviewer
--reason <value>	Review evidence

Provides deterministic project management workflows for humans and coding agents.

--id <value>	Filter by item ID
--op <value>	Filter by history operation
--author <value>	Filter by history author
--from <value>	Lower timestamp bound (ISO/date string or relative)
--to <value>	Upper timestamp bound (ISO/date string or relative)
--limit <n>	Return only the latest n activity entries
--unbounded	Explicitly return every matching activity entry (disables the default bound)
--compact	Condensed output: show only id, op, ts, author, msg per entry
--raw	Show the legacy compact per-event stream instead of the item digest
--full	Show full activity entries with JSON Patch payloads
--provenance	Show patch-free author, harness, instance, and extensible provenance
--provenance-summary	Include bounded provenance completeness counts
--harness <value>	Filter by recorded or vocabulary-resolved harness (repeatable)
--agent-instance <value>	Filter by privacy-safe agent instance (repeatable)
--provenance-filter <dimension=value>	Filter by an exact declared provenance value (repeatable)
--stream [mode]	Emit line-delimited JSON rows (requires --json). Optional mode: rows|ndjson|jsonl

Provides deterministic project management workflows for humans and coding agents.

--verify <file>	Compare retained streams with a detached JSON proof
--output <file>	Create a proof file and return a compact receipt
--hash-algorithm <name>	Bundle digest algorithm: sha256 (default) or sha512

Provides deterministic project management workflows for humans and coding agents.

<id>	Item id (omit when using a bulk selector)

--before <value>	Compact entries strictly before this version number or ISO timestamp (single-id mode only)
--ids <value>	Bulk IDs: comma/newline text, - stdin, or @path file
--all-over <n>	Bulk: compact every stream with more than N entries
--closed	Bulk: compact only closed (terminal) items' streams
--all-streams	Bulk: compact every history stream regardless of lifecycle state
--min-entries <n>	Bulk: skip streams with at most N entries (already compact; default 3)
--dry-run	Preview compaction impact without writing the history file
--author <value>	Mutation author
--message <value>	Audit history message for the compaction marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

--since <cursor-or-timestamp>	Resume strictly after a durable cursor, or include events from an ISO timestamp
--type <value>	Filter by mutation operation (repeatable or comma-separated)
--author <value>	Filter by mutation author (repeatable or comma-separated)
--item <value>	Filter by item or workspace stream id (repeatable or comma-separated)
--limit <n>	Return at most 1,000 events (default: 100)
--cursor-mode <mode>	Cursor framing: batch emits one terminal trailer (default); row preserves one cursor per event
--full	Include each complete authoritative history entry
--provenance	Include patch-free author, harness, instance, and extensible provenance
--provenance-summary	Include bounded provenance completeness counts
--harness <value>	Filter by recorded or vocabulary-resolved harness (repeatable)
--agent-instance <value>	Filter by privacy-safe agent instance (repeatable)
--provenance-filter <dimension=value>	Filter by an exact declared provenance value (repeatable)
--follow	Continue emitting committed events as newline-delimited JSON
--interval-ms <n>	Empty-read delay while following (minimum: 10ms; default: 250ms)

Provides deterministic project management workflows for humans and coding agents.

<id> required

Item id

--literal <value>	Literal string to redact (repeatable)
--regex <value>	Regex pattern to redact (repeatable; accepts /pattern/flags or raw pattern)
--replacement <value>	Replacement string (default: "[redacted]")
--dry-run	Preview redaction impact without writing item/history files
--author <value>	Mutation author
--message <value>	Audit history message for the redaction marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

<id>	Item id (omit with --all)

--salvage-tail	Recover invalid tail; requires verified prefix
--all	Scan every stream for drift and repair each drifted stream in one audited pass
--dry-run	Preview the re-anchor impact without writing the history file
--normalize-provenance	Remove invalid provenance; return aggregate-only evidence
--author <value>	Mutation author
--message <value>	Audit history message for the repair marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

<id> required	Item id
<target> required	Restore target timestamp or version number

--author <value>	Mutation author
--message <value>	History message
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

--verify <file>	Compare retained streams with a detached JSON proof
--output <file>	Create a proof file and return a compact receipt
--hash-algorithm <name>	Bundle digest algorithm: sha256 (default) or sha512

Provides deterministic project management workflows for humans and coding agents.

--event <item-id:line>	Unknown-author event coordinate (repeatable)
--all-actionable	Select all actionable events
--dry-run	Preview a deterministic source-bound plan
--plan-fingerprint <sha256>	Apply the exact fingerprint returned by --dry-run
--limit <n>	Maximum coordinate rows returned in the plan
--attributed-author <value>	Reviewed principal attribution
--reviewer <value>	Disposition reviewer
--reason <value>	Review evidence

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.

<id>	Item id (omit when using a bulk selector)

--before <value>	Compact entries strictly before this version number or ISO timestamp (single-id mode only)
--ids <value>	Bulk IDs: comma/newline text, - stdin, or @path file
--all-over <n>	Bulk: compact every stream with more than N entries
--closed	Bulk: compact only closed (terminal) items' streams
--all-streams	Bulk: compact every history stream regardless of lifecycle state
--min-entries <n>	Bulk: skip streams with at most N entries (already compact; default 3)
--dry-run	Preview compaction impact without writing the history file
--author <value>	Mutation author
--message <value>	Audit history message for the compaction marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

<id> required

Item id

--literal <value>	Literal string to redact (repeatable)
--regex <value>	Regex pattern to redact (repeatable; accepts /pattern/flags or raw pattern)
--replacement <value>	Replacement string (default: "[redacted]")
--dry-run	Preview redaction impact without writing item/history files
--author <value>	Mutation author
--message <value>	Audit history message for the redaction marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

<id>	Item id (omit with --all)

--salvage-tail	Recover invalid tail; requires verified prefix
--all	Scan every stream for drift and repair each drifted stream in one audited pass
--dry-run	Preview the re-anchor impact without writing the history file
--normalize-provenance	Remove invalid provenance; return aggregate-only evidence
--author <value>	Mutation author
--message <value>	Audit history message for the repair marker entry
--force	Force ownership/lock override

Provides deterministic project management workflows for humans and coding agents.

Adds implementation notes to body without replacing existing content.

<id> required	Item id
<text>	Body text; same as --body (- reads stdin)

--body <value>	Text to append to body (or - for stdin)
--author <value>	Mutation author
--message <value>	Mutation message
--force	Force ownership override

Provides deterministic project management workflows for humans and coding agents.

<id> required
<reason>

--transaction-id <value> required	Stable idempotency key for the composed completion
--reason <value>	Close reason when omitted positionally
--file <value>	Linked file evidence
--doc <value>	Linked documentation evidence
--test <value>	Linked test evidence
--comment <value>	Evidence comment
--note <value>	Completion note
--learning <value>	Durable completion learning
--resolution <value>	Structured resolution evidence
--expected-result <value>	Expected result evidence
--actual-result <value>	Actual result evidence
--completed-at <value>	Actual completion time
--validate-close <mode>	Close validation: off, warn, or strict
--lock-ttl-seconds <n>	Workspace transaction lock lifetime in seconds
--lock-wait-ms <n>	Maximum time to wait for the workspace transaction lock
--dry-run	Validate and preview completion without writing
--force	Override lifecycle and ownership conflicts
--author <value>	Completion author

Provides deterministic project management workflows for humans and coding agents.

<id> required

Source item id

--title <value>	Optional title override for the copied item
--author <value>	Mutation author
--message <value>	History message
--allow-duplicate	Explicitly copy even when strict similarity governance finds likely duplicates

Inspects an item dependency graph as a tree or graph payload to understand blockers and hierarchy links.

<id> required

Item id

--format <value>	Output format (tree, graph, or context)
--max-depth <value>	Maximum dependency traversal depth (0 keeps only the root)
--collapse <value>	Collapse mode (none or repeated)
--summary	Return counts only without full tree/graph payload
--full	Return the complete dependency row projection
--node-limit <value>	Maximum nodes in context output
--edge-limit <value>	Maximum edges and missing-reference rows in context output
--token-budget <value>	Maximum estimated tokens in context output
--cursor <value>	Continue an equivalent context query
--direction <value>	Context traversal direction (outgoing, incoming, or both)
--kind <value>	Restrict context traversal to registered relationship kinds (repeatable or comma-separated)

Associates relevant documentation paths with tracker items.

<id> required

Item id

--add <value>	Add linked doc entry (CSV/markdown pairs or - for stdin)
--add-glob <value>	Add linked doc entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)
--remove <value>	Remove linked doc by path only (path=<value>, path:<value>, plain path, or - for stdin); does not accept note=/scope= — record removal context with --message
--migrate <value>	Migrate linked doc paths in-place (from=<prefix>,to=<prefix>; repeatable)
--note <value>	Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)
--list	List linked docs without mutating
--validate-paths	Validate linked doc paths for existence and file shape
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Provides deterministic project management workflows for humans and coding agents.

--status <value>	Statuses (repeatable or comma-separated)
--since <value>	Created at or after this time
--threshold <value>	Minimum similarity (0-1)
--limit <n>	Maximum clusters
--exhaustive	Score all pairs within the safety bound

Associates changed source files with tracker items for reproducibility.

<id> required

Item id

--add <value>	Add linked file entry (CSV/markdown pairs or - for stdin)
--add-glob <value>	Add linked file entries from a glob (plain glob or pattern=<glob>,scope=<scope>,note=<text>; repeatable)
--remove <value>	Remove linked file by path only (path=<value>, path:<value>, plain path, or - for stdin); does not accept note=/scope= — record removal context with --message
--migrate <value>	Migrate linked file paths in-place (from=<prefix>,to=<prefix>; repeatable)
--note <value>	Note attached to every link added by --add/--add-glob in this invocation (embedded note= wins)
--list	List linked files without mutating
--append-stable	Preserve existing linked-file order and append new links without full-array resorting
--validate-paths	Validate linked file paths for existence and file shape
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Provides deterministic project management workflows for humans and coding agents.

--transaction-id <value> required	Stable idempotency key used to resume an interrupted batch
--stdin-json	Read the JSON mutation array from stdin
--dry-run	Validate and preview the batch without writing
--create-compensation <mode>	Created-item compensation policy: close or delete
--lock-ttl-seconds <n>	Workspace transaction lock lifetime in seconds
--lock-wait-ms <n>	Maximum time to wait for the workspace transaction lock
--author <value>	Mutation author

Provides deterministic project management workflows for humans and coding agents.

<id> required
<reason> required

--status <value>	Active target status: open or in_progress
--message <value>	Human-readable recurrence history message
--force	Override ownership or stale-lock conflicts
--author <value>	Mutation author

Links test commands/paths and optionally executes them for one item.

<id> required

Item id

--add <value>	Add verified isolated test (CSV/markdown or stdin)
--add-json <value>	Add verified isolated test (JSON object/array or stdin)
--remove <value>	Remove linked test entry by exact command/path (command=<value> and path=<value> preserve commas and equals signs; or - for stdin)
--remove-index <n>	Remove the 1-based linked-test index from --list order (repeatable)
--list	List linked tests without mutating
--run	Run linked test commands
--match <value>	Run only linked tests whose command/path contains this substring
--only-index <n>	Run only the 1-based linked-test index from --list order
--only-last	Run only the most recently added linked test
--acknowledge-linked-tests	Trust the item's current linked commands in this clone without executing them
--background	Run linked tests in managed background mode
--timeout <seconds>	Default run timeout in seconds
--progress	Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)
--env-set <value>	Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)
--env-clear <value>	Clear environment variable(s) for linked-test runs (NAME, repeatable)
--shared-host-safe	Apply additive shared-host-safe runtime defaults for linked-test runs
--pm-context <mode>	PM linked-test context mode: schema|tracker|auto (default: schema)
--override-linked-pm-context	Force run-level --pm-context to override per-linked-test pm_context_mode metadata
--workspace-context <mode>	Source-workspace mode: source|isolated|snapshot (default: source)
--override-linked-workspace-context	Force run-level --workspace-context over per-linked-test metadata
--allow-untrusted-linked-tests	Execute untrusted linked commands when project policy also permits it
--fail-on-context-mismatch	Fail linked PM commands when context item counts differ
--fail-on-skipped	Treat skipped linked tests as dependency failures
--fail-on-empty-test-run	Treat successful linked-test commands that report zero executed tests as failures
--require-assertions-for-pm	Require assertion metadata for linked PM command tests
--check-context	Preflight linked PM command context diagnostics before executing commands
--auto-pm-context	Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context
--measure <value>	Record name=value[,unit=...][,threshold=...] evidence; repeatable
--metric-below <value>	Return evidence below name=value
--metric-diff <name>	Diff the latest two values
--author <value>	Mutation author
--message <value>	History message
--force	Force ownership override

Provides deterministic project management workflows for humans and coding agents.

<runId> required

Background run id

Provides deterministic project management workflows for humans and coding agents.

<subcommand> required	Merge subcommand: install, reconcile, report, driver
<artifact>	driver only: artifact class to merge (item, history, relationship, json)
<base>	driver only: common-ancestor file path (git %O)
<ours>	driver only: current-branch file path (git %A)
<theirs>	driver only: other-branch file path (git %B)

--dry-run	install/reconcile: preview changes without writing
--message <text>	reconcile only: audit message recorded on repaired history streams
--force	reconcile only: permit the underlying audited history ownership override
--include-reconciled	report only: include clone-local receipts already recorded in history
--output <path>	driver only: write the merged content to this path instead of the ours path
--item-path <path>	driver only: original repository-relative path supplied by git as %P
--prefer <side>	driver only: side that wins unresolvable conflicts (ours|theirs; default ours)

Answers 'what should I work on now?' with the highest-priority ready item, rationale, and ranked ready and blocked queues.

--for <intent>	Apply a declared context intent projection. Allowed core values: execute. Configured package and workspace intents may extend this domain.
--type <value>	Filter candidate items by type
--tag <value>	Filter candidate items by tag
--priority <value>	Filter candidate items by priority
--assignee <value>	Filter candidate items by assignee
--assignee-filter <value>	Filter assignee presence: assigned|unassigned
--sprint <value>	Filter candidate items by sprint
--release <value>	Filter candidate items by release
--parent <id>	Scope to one item's subtree (the item plus all descendants)
--limit <n>	Limit ready rows (default: 5; non-positive falls back to default)
--blocked-limit <n>	Limit blocked rows (default: same as --limit)
--ready-only	Omit the blocked companion list
--include-decisions	Include human-gated Decision items in the claimable ready queue
--include-gates	Include outcome gates in the ready queue
--include-containers	Include containers with unfinished descendants in the ready queue
--format <value>	Next output format override: markdown|toon|json
--explain-ranking	Include the scorer model, per-signal contributions, and ranked ready ids
--token-budget <n>	Maximum estimated tokens spent on the ranked ready queue

Groups workspace diagnostics, quality checks, and maintenance under one discoverable command.

Measures search relevance against a curated golden-query set so retrieval regressions are caught, not guessed.

--mode <value>	Default retrieval mode for queries without their own: keyword|semantic|hybrid (default: keyword)
--k <n>	Metric cutoff @k (positive integer; default: 10)
--fail-under <value>	Exit non-zero when aggregate nDCG@k falls below this threshold (0..1); CI gate
--queries <path>	Query JSON (https://schema.unbrained.dev/pm/eval-query-set/v1); default: search/eval-queries.json; errors show an example
--format <value>	Eval output format override: json|toon

Deletes optional cache artifacts by default to keep local tracker state tidy; use --dry-run to preview targets without deleting files.

--dry-run	Preview cleanup targets without deleting files; without this flag, pm gc deletes matched artifacts
--scope <value>	Limit cleanup to one or more scopes (comma-separated or repeatable): index, embeddings, runtime, locks, checkpoints, transactions

Validates tracker/runtime health including extension triage, migration, and integrity diagnostics.

--strict-directories	Treat optional item-type directories as required failures
--require-merge-drivers	Treat absent clone-local merge drivers as a required health failure
--check-only	Run read-only health diagnostics without refreshing vectors
--check-telemetry	Probe telemetry endpoint health and include network diagnostics
--no-refresh	Disable automatic vector refresh attempts during health checks
--refresh-vectors	Explicitly enable vector refresh attempts during health checks
--verbose-stale-items	Include full stale vectorization ID lists in health output
--verbose-author-events	Include every actionable unknown-author event coordinate for review or disposition
--brief	Emit compact health details for low-token agent checks
--summary	Emit one-line-style health status with check names and warning count
--skip-vectors	Skip vectorization check for a faster run
--skip-integrity	Skip item/history file integrity check for a faster run
--skip-drift	Skip history drift hash check for a faster run
--full	Run all checks including slow integrity, drift, and vectorization checks
--strict-exit	Return non-zero exit when health is not ok and default to actionable summary output; use --full for complete details

Reports tracker-level totals and distribution by type/status.

--include-empty	Restore zero-count registered item-type and lifecycle-status buckets
--storage	Include aggregate history-stream storage metrics (total streams/lines/bytes, largest + deepest streams, oldest/newest entries)
--metadata-coverage	Include metadata coverage % (acceptance_criteria, estimated_minutes, resolution, tags, parent) overall and by type
--by-assignee	Include a lifecycle-bucketed item breakdown grouped by assignee
--by-tag	Include a lifecycle-bucketed item breakdown grouped by tag
--by-priority	Include a lifecycle-bucketed item breakdown grouped by priority
--tag-prefix <value>	With --by-tag: only count tags starting with this prefix (e.g. domain:)
--field-utilization	Report content-field utilization rates (notes/learnings/files/docs/tests/comments/deps/body) for governance analysis
--analytics <json>	Improvement ledger/history analytics JSON

Inspects and manages local telemetry queue/runtime state for observability diagnostics.

<namespace-or-subcommand>	Telemetry subcommand: status, flush, stats, clear (default: status)
<subcommand>	Compatibility alias target for local-analytics: status, flush, stats, clear

--limit <n>

Maximum command groups returned by telemetry stats

Runs linked tests in bulk for release/readiness sweeps.

--status <value>	Filter items by status before running tests
--limit <n>	Limit matching items before running linked tests
--offset <n>	Skip matching items before running linked tests
--background	Run linked tests in managed background mode
--timeout <seconds>	Default run timeout in seconds
--progress	Emit linked-test progress to stderr (always shown in TTY, opt-in for non-TTY)
--env-set <value>	Set environment variable(s) for linked-test runs (KEY=VALUE, repeatable)
--env-clear <value>	Clear environment variable(s) for linked-test runs (NAME, repeatable)
--shared-host-safe	Apply additive shared-host-safe runtime defaults for linked-test runs
--pm-context <mode>	PM linked-test context mode: schema|tracker|auto (default: schema)
--override-linked-pm-context	Force run-level --pm-context to override per-linked-test pm_context_mode metadata
--workspace-context <mode>	Source-workspace mode: source|isolated|snapshot (default: source)
--override-linked-workspace-context	Force run-level --workspace-context over per-linked-test metadata
--allow-untrusted-linked-tests	Execute untrusted linked commands when project policy also permits it
--fail-on-context-mismatch	Fail linked PM commands when context item counts differ
--fail-on-skipped	Treat skipped linked tests as dependency failures
--fail-on-empty-test-run	Treat successful linked-test commands that report zero executed tests as failures
--require-assertions-for-pm	Require assertion metadata for linked PM command tests
--check-context	Preflight linked PM command context diagnostics before executing commands
--auto-pm-context	Auto-remediate PM tracker-read context mismatches by routing those linked commands through tracker context

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.

--check-metadata	Run metadata completeness checks
--metadata-profile <value>	Metadata profile (core|strict|custom)
--check-resolution	Run closed-item resolution metadata checks
--check-completeness	Check declarative lifecycle field requirements
--check-lifecycle	Run active-item lifecycle governance drift checks
--check-stale-blockers	Include stale blocker-pattern diagnostics in lifecycle checks
--dependency-cycle-severity <value>	Set dependency-cycle warning policy for lifecycle checks (off|warn|error)
--parent-cycle-severity <value>	Set parent-hierarchy cycle warning policy for lifecycle checks (off|warn|error)
--check-files	Run linked-file and orphaned-file checks
--check-command-references	Run linked-command PM-ID reference checks
--scan-mode <value>	Select file candidate scan mode for --check-files (default|tracked-all|tracked-all-strict)
--include-pm-internals	Include PM storage internals in tracked-all candidate scans
--verbose-file-lists	Include full file-path lists for validate --check-files details
--verbose-diagnostics	Include full diagnostic ID lists
--all-affected-ids	Emit complete missing_* affected-ID lists with no truncation (implied by --json)
--strict-exit	Return non-zero exit when validation warnings are present
--fix-hints	Add a machine-executable fix_hints[] of pm commands to each failing check's details
--auto-fix	Apply safe, deterministic field backfills
--dry-run	Preview planned --auto-fix/--prune-missing fixes without applying them
--fix-scope <scope>	Grant --auto-fix scopes (metadata, resolution, estimates, timestamps, lifecycle; comma-separated or repeatable). Default: metadata, resolution; other scopes require explicit opt-in
--prune-missing	Remove deleted-path file/doc links; preserves real files
--check-history-drift	Run item/history hash drift checks
--check-storage-integrity	Run the post-merge storage-integrity check (unreadable items, history conflict markers, resurrected deletes, unparseable config/schema)
--counts	Keep validation counts and totals while omitting per-item diagnostic arrays
--full	Return the complete validation diagnostic projection

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--gh <owner/repo[/path]>	GitHub provenance shorthand for adopted package
--ref <ref>	Git ref/branch/tag for GitHub shorthand source
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project package scope (default)
--global	Use global package scope

Lists bundled first-party package catalog metadata and compact field projections.

--fields <value>	Render compact comma-separated catalog fields, for example: alias,installed,install_command
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target>

Package name to describe (omit for every loaded package)

--markdown	Render the surface map as a Markdown reference document instead of toon/json
--output <path>	Write Markdown output to a file (requires --markdown)
--project	Use project package scope (default)
--global	Use global package scope

Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.

--detail <mode>	Detail mode for package diagnostics (summary|deep)
--trace	Include actionable registration traces in doctor deep diagnostics
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--isolated	Run doctor against project-scope packages only, ignoring global registrations
--strict-exit	Return non-zero exit when doctor warnings are present (ok=false)
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project package scope (default)
--global	Use global package scope

Generates an installable starter pm package with package metadata and a root extension entrypoint.

<target> required

Scaffold target directory path

--capability <kind>	Capability the starter targets (commands|hooks|search|importers|schema|profile|renderers|parser|preflight|services; default commands)
--declarative	Scaffold the composeExtension blueprint starter (any capability)
--project	Use project package scope (default)
--global	Use global package scope

Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.

<targets>

Package source (local path, bundled alias, npm: source, wildcard, or GitHub source)

--dry-run	Resolve sources and estimate copying without destination writes or activation
--gh <github-source>	Install from GitHub shorthand source (owner/repo[/path])
--ref <ref>	Git ref/branch/tag for GitHub install sources
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--runtime-probe	Opt-in runtime activation probe for manage output parity
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--dry-run	Plan active migrations without invoking extension code
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--watch	Use watch mode for repeated reload checks
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target>

Optional managed package name/source to upgrade; omit to upgrade pm CLI and all managed packages

--project	Use project package scope (default)
--global	Use global package scope
--dry-run	Plan CLI/package upgrades without running npm or reinstalling packages
--cli-only	Upgrade only the pm CLI/SDK npm package
--packages-only	Upgrade only managed pm packages
--repair	Force npm global reinstall when upgrading the pm CLI/SDK
--tag <value>	npm dist-tag/version for CLI and registry package upgrades
--package-name <value>	Override the CLI package name for self-upgrade testing

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--gh <owner/repo[/path]>	GitHub provenance shorthand for adopted package
--ref <ref>	Git ref/branch/tag for GitHub shorthand source
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project package scope (default)
--global	Use global package scope

Lists bundled first-party package catalog metadata and compact field projections.

--fields <value>	Render compact comma-separated catalog fields, for example: alias,installed,install_command
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target>

Package name to describe (omit for every loaded package)

--markdown	Render the surface map as a Markdown reference document instead of toon/json
--output <path>	Write Markdown output to a file (requires --markdown)
--project	Use project package scope (default)
--global	Use global package scope

Diagnoses package activation, policy, collision, and managed-state health for project or global package scopes.

--detail <mode>	Detail mode for package diagnostics (summary|deep)
--trace	Include actionable registration traces in doctor deep diagnostics
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--isolated	Run doctor against project-scope packages only, ignoring global registrations
--strict-exit	Return non-zero exit when doctor warnings are present (ok=false)
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--project	Use project package scope (default)
--global	Use global package scope

Generates an installable starter pm package with package metadata and a root extension entrypoint.

<target> required

Scaffold target directory path

--capability <kind>	Capability the starter targets (commands|hooks|search|importers|schema|profile|renderers|parser|preflight|services; default commands)
--declarative	Scaffold the composeExtension blueprint starter (any capability)
--project	Use project package scope (default)
--global	Use global package scope

Installs pm packages from local paths, npm sources, GitHub sources, bundled aliases, or wildcard/all aliases.

<targets>

Package source (local path, bundled alias, npm: source, wildcard, or GitHub source)

--dry-run	Resolve sources and estimate copying without destination writes or activation
--gh <github-source>	Install from GitHub shorthand source (owner/repo[/path])
--ref <ref>	Git ref/branch/tag for GitHub install sources
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--runtime-probe	Opt-in runtime activation probe for manage output parity
--fix-managed-state	Adopt unmanaged packages before diagnostics/update checks
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--dry-run	Plan active migrations without invoking extension code
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

--watch	Use watch mode for repeated reload checks
--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target> required

Package name

--project	Use project package scope (default)
--global	Use global package scope

Provides deterministic project management workflows for humans and coding agents.

<target>

Optional managed package name/source to upgrade; omit to upgrade pm CLI and all managed packages

--project	Use project package scope (default)
--global	Use global package scope
--dry-run	Plan CLI/package upgrades without running npm or reinstalling packages
--cli-only	Upgrade only the pm CLI/SDK npm package
--packages-only	Upgrade only managed pm packages
--repair	Force npm global reinstall when upgrading the pm CLI/SDK
--tag <value>	npm dist-tag/version for CLI and registry package upgrades
--package-name <value>	Override the CLI package name for self-upgrade testing

Append one ordered step to a Plan item.

<plan-id> required

item id value.

--step-title <value>	Step title for add-step / update-step
--step-body <value>	Step body text
--step-owner <value>	Step owner
--step-status <value>	Step status: pending|in_progress|completed|blocked|skipped|superseded
--step-evidence <value>	Step evidence text (used by update-step/complete-step)
--step-blocked-reason <value>	Step blocked reason (required when blocking)
--depends-on <value>	Pm item ids the step depends on (repeatable, csv-friendly)
--allow-multiple-active	Allow multiple steps to be in_progress at once
--file <value>	Step linked file path=<value>[,scope=project|global,note=<text>] (repeatable)
--test <value>	Step linked test command=<value>[,path=<value>,note=<text>] (repeatable)
--message <value>	Mutation message
--force	Force ownership override

Approve for one Plan item.

<plan-id> required

item id value.

--step-title <value>	Step title for add-step / update-step
--step-body <value>	Step body text
--step-owner <value>	Step owner
--step-status <value>	Step status: pending|in_progress|completed|blocked|skipped|superseded
--step-evidence <value>	Step evidence text (used by update-step/complete-step)
--step-blocked-reason <value>	Step blocked reason (required when blocking)
--depends-on <value>	Pm item ids the step depends on (repeatable, csv-friendly)
--allow-multiple-active	Allow multiple steps to be in_progress at once
--file <value>	Step linked file path=<value>[,scope=project|global,note=<text>] (repeatable)
--test <value>	Step linked test command=<value>[,path=<value>,note=<text>] (repeatable)
--message <value>	Mutation message
--force	Force ownership override

Block one declared Plan step.

<plan-id> required	item id value.
<step> required	string value.

--step-title <value>	Step title for add-step / update-step
--step-body <value>	Step body text
--step-owner <value>	Step owner
--step-status <value>	Step status: pending|in_progress|completed|blocked|skipped|superseded
--step-evidence <value>	Step evidence text (used by update-step/complete-step)
--step-blocked-reason <value>	Step blocked reason (required when blocking)
--depends-on <value>	Pm item ids the step depends on (repeatable, csv-friendly)
--allow-multiple-active	Allow multiple steps to be in_progress at once
--file <value>	Step linked file path=<value>[,scope=project|global,note=<text>] (repeatable)
--test <value>	Step linked test command=<value>[,path=<value>,note=<text>] (repeatable)
--message <value>	Mutation message
--force	Force ownership override