Agent safety: 'pm test <id> --add --help' (and 'pm files --add --help') records '--help' as a linked test/file instead of printing help

[unbraind]

Repro (pm 2026.10.4, fresh workspace)

pm init
id=$(PM_AUTHOR=x pm create --type Task --title t --description d --create-mode progressive --json | jq -r .id)
PM_AUTHOR=x pm test  $id --add --help    # ok: true  → tests: [{command: "--help", scope: project}]
PM_AUTHOR=x pm files $id --add --help    # ok: true  → files[1]{path,scope}: "--help",project

Both commands mutate the item (with a history record) instead of printing help, and report ok: true.

Why it matters

Agents routinely append --help to the command they are about to run to discover its grammar. In a real package tracker (unbraind/pm-ops, item ops-zq8c) an agent did exactly this, the bogus {command: "--help"} test was committed, and a reviewer had to flag it on the PR ("Recorded test cannot run"). Because pm test --run executes recorded commands, this also turns help discovery into a persisted executable entry.

Expected

• --help/-h anywhere in argv prints the command's help and exits 0 without mutating, as for every other command; or
• a value-taking collection option refuses a value that is itself a known global flag (--help, --json, --dry-run, …) with a recovery hint (use --add=--help if you really mean the literal).

Related: #1337 (unsupported --dry-run recovery suggests the real mutation) — same class: discovery flags must never be swallowed as mutation values.

[unbraind]

Canonical PM item: pm-gh1398. Implementation, tests, typed lineage and immutable closure are part of the single PR #1402; the main item link becomes available when this delivery merges.

Fresh Greptile review of prior15191ebaa independently exposed update -b -h body mutation and unintended create --file --help creation. An isolated old-source run fails eight intended assertions. The first complete correction also caught a real global JSON-help regression; an isolated pre-correction source fails five assertions. The final SDK normalization preserves authoritative global boolean presentation while neutralizing the immediately preceding declared option and retaining reachable help. The primary SDK/real CLI suites pass all118 cases; actual newly packed Node/Bun consumers preserve durable bytes and task membership, including root --json --help, explicit literals, aliases, adjacent options and terminators.

All9772 tests in775 files pass at exact100/100/100/100; complete static/typecheck, linked verification, nine-package npx/bunx smoke and all nine final delivery gates pass. The canonical item is closed/released with structured expected/actual evidence. Head a5a5632 is pushed and both requested reviews plus all protected hosted checks are waiting; older-head results are not substituted for this admission.