pm --help omits 15 of 29 working commands, including health, comment, docs, test, merge and events #1127

pm --help lists 14 commands. 15 more are fully implemented, documented and working — including health, comment, docs, test, merge, events and graph — but appear in no help listing at all.

For an agent this is the difference between a tool it can use and a tool it cannot find. Command discovery is the first thing an agent does in an unfamiliar repo, and pm --help is the canonical place to do it.

Reproduction

Clean workspace, no project config, extensions disabled, pm 2026.8.24:

$ cd "$(mktemp -d)"
$ pm --help --no-extensions | sed -n '/^Commands:/,/^$/p' | awk 'NR>1{print $1}'
init
list
context|ctx
next
search
get
create
update
close
plan
validate
claim
release
help

Every one of these then works, from the same clean directory:

$ pm health --help
Usage: pm health [options]

Show project tracker health checks.

$ pm help health          # also works
$ pm comment --help       # works
$ pm docs --help          # works

Full set that works but is never listed (15):

health comment docs test merge events graph duplicates note learning history stats config install extension

That is 15 unlisted against 14 listed — more than half the surface is invisible.

Not a display or budget artefact

• Identical with --output-budget unbounded (42 lines either way), so it is not the output ceiling trimming the list.
• Identical with --no-extensions, and identical in a clean temp directory with no tracker and no project config, so it is not extension registration or local state.
• --explain does not reveal them, and neither does bare pm help.
• pm help <cmd> renders correct, complete help for each one — the metadata exists, it just never reaches the listing.

Why it matters beyond convenience

The unlisted set is not a handful of aliases; it is much of what makes the tool useful to an agent:

• pm health is the tracker's own integrity gate. An agent that cannot discover it cannot check tracker state before mutating it.
• pm comment, pm note, pm learning, pm docs, pm test are the entire evidence-recording surface — the part that makes project management = context management true rather than aspirational.
• pm merge and pm events are what multi-agent workflows depend on.

An agent that reads pm --help and takes it as the contract will conclude the tool cannot record evidence and cannot report health, and will work around it — writing findings into commit messages or ad-hoc files instead of the tracker. That is a silent, self-inflicted loss of exactly the context the tool exists to keep.

Suggested fix

Whatever registers these commands is bypassing the path that populates the listing. Either register them through the same path, or if some are deliberately de-emphasised, mark them explicitly and surface them under a heading (pm --help --explain would be a natural home) rather than omitting them.

A regression test worth having: assert that every command that answers pm help <name> also appears in pm --help. That invariant is cheap to check and would have caught this.

Found while auditing tracker usage across 21 packages that use pm for their own project management.