@unbrained/pm-cli 2026.10.28 → 2026.10.31

package/docs/AGENT_UX_CONTRACTS.md

@@ -68,10 +68,11 @@ When an agenda event belongs to an item already emitted in `high_level`, `low_le
 
 Claim conflicts distinguish stored assignment from an explicit claim:
 
-- `assigned to <identity>` means assignment metadata owns the current value.
+- `assigned to <identity>` means assignment metadata owns the current value. The same phrase is used when history cannot establish the origin (unreadable history, no assignee change recorded, or a newest change that set a different holder); then `claim_source` is `unknown` and `claimed_at` is `null`, so read `claim_source` rather than the phrase when the origin matters.
 - `claimed by <identity>` means the latest ownership mutation was `pm claim`.
 
 The structured conflict code remains `already_claimed_by` for compatibility with atomic claim retry loops.
+The refusal also carries the holder as typed fields (`claimed_by`, `claim_source`, `claimed_at`) in the error context, the JSON envelope and the public SDK `PmCliErrorContext`, so a retry loop can decide to wait, skip or coordinate without parsing the sentence; `resolveItemOwnershipConflict` exposes the same evidence to packages.
 
 ## Input and tracker recovery
 

package/docs/COMMANDS.md

@@ -169,6 +169,31 @@ pm next --parent pm-epic01              # scope readiness to one epic's subtree
 pm next --ready-only --limit 3 --json   # tightest agent-loop projection
 ```
 
+`pm next` has two budgets with different scopes. `--token-budget <n>` bounds
+only the selection (`recommended` plus `ready`) and reports it under
+`truncation.ready_budget`; `filters.token_budget` echoes that request and is
+`null` when none was made. The complete response, including `decision_needed`,
+`containers`, `blocked` and `held_by_others`, is bounded by the universal
+output budget (`--output-budget`, default ceiling of the read class) and
+disclosed by the `read_output` receipt, which a selection budget now always
+triggers so the total cost and the ceiling that bound it are visible. Use
+`--token-accounting` for per-section bytes. Companion sections are not
+visibility toggles: `--include-decisions`, `--include-gates` and
+`--include-containers` move those rows into the claimable `ready` queue.
+
+The ready queue is ordered by a declared policy, disclosed as
+`filters.ranking_policy`. The default, `priority_floor`, resumes in-progress
+work first, then orders ready items by priority tier and lets the relevance
+score (recency, activity, deadlines, graph proximity) order items only within
+a tier, so an automated log that gains a comment every hour cannot outrank a
+ready P0 incident (GH-1618). `weighted` keeps the blended relevance order. Set
+it per tracker with `pm config project set context_next_ranking_policy
+weighted` (SDK callers pass `rankingPolicy`); a project's own
+`context_relevance` scorer keeps its order under either policy. When the
+policy and the score disagree, the recommendation's `reasons` say so
+(`priority floor (relevance rank N)` or `relevance over pN ready work`), and
+`--explain-ranking` still shows every item's score beside its final rank.
+
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
 Use `duplicates --status all` for a true whole-history duplicate check. The
 result echoes `filters.statuses: null` for the unrestricted corpus; named or
@@ -495,7 +520,7 @@ it does not implicitly force an ownership or lock override.
 New checkpoints use schema version 2 so older CLI versions also refuse them
 instead of applying their former whole-item restoration behavior.
 
-When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`). Unknown-command guidance ranks agent verb synonyms first, bounded edit distance second, and substring matches last; `pm log` therefore points to `history`, `comments`, and `notes`, never a `catalog` command.
+When a flag is rejected with `Unknown option`, the error guidance now suggests the nearest supported flag (including abbreviations like `--desc` → `--description`) and notes when the flag is valid on a different command (for example `--type` on `test-all` points to `create`/`list`). A quoted value that starts with `--` and contains spaces, such as a close reason `"--unset is now a list"`, is parsed as an unknown option. Its refusal says so, and its replay never drops the value. When only options follow the value, the replay passes it after a `--` separator, for example `pm close <id> -- "--unset is now a list"`. Otherwise the refusal explains how to pass it ([pm-stq61b](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-stq61b.toon); repository-only tracker record excluded from npm). Unknown-command guidance ranks agent verb synonyms first, bounded edit distance second, and substring matches last; `pm log` therefore points to `history`, `comments`, and `notes`, never a `catalog` command.
 
 Commands addressed to one item retain their canonical positional form and also accept `--id <item-id>` consistently. For example, `pm get --id pm-a1`, `pm comments --id pm-a1 --add "..."`, and `pm test --id pm-a1 --run` are equivalent to their positional forms. Supplying both forms is a usage error. Command-scoped `pm contracts --flags-only`, completion, and help expose the same alias.
 
@@ -645,9 +670,22 @@ pm --id-only create "Probe item"             # output is only id + status
 
 For strict JSON consumers, the global `--lean` flag recursively omits null,
 undefined, empty-array, and empty-object noise while preserving meaningful
-false/zero/empty-string values. On usage failures it keeps only actionable
-error fields (`type`, `code`, `detail`, `exit_code`, examples, next steps, and
-recovery), reducing retry context without hiding the deterministic fix:
+false/zero/empty-string values. On refusals it keeps only the fields that
+change the next action: `type`, `code`, `detail`, `exit_code`, `next_steps`,
+code-specific `required`/`examples`/`why`, specific recovery
+(`suggested_retry`, `missing`, `allowed_values`, `next_best_command`) and
+typed evidence such as the holder fields below. The generic requirement, the
+`pm --help` examples and the invocation echo (`attempted_command`,
+`normalized_args`, `provided_fields`) are dropped, in text as well as JSON,
+so a lean refusal is never larger than its default rendering (GH-1610). Text
+refusals print a single-line message once, as the headline, and repeat it
+under `What happened` only when the headline is a classification.
+An `already_claimed_by` refusal carries the holder as typed fields in every
+mode: `claimed_by`, `claim_source` (`claim`, `assignment`, or `unknown`
+when history is unreadable, silent, or names a different holder) and
+`claimed_at` (the latest assignee change, or `null` when the origin is
+unknown); text output renders them as `Held by: <holder> (<source> since
+<time>)` and caps a very long holder name, which JSON keeps whole.
 
 ```bash
 pm --json --lean get pm-a1b2
@@ -662,6 +700,8 @@ Use `pm close <duplicate-id> --duplicate-of <canonical-id>` to close duplicates.
 
 Every transition into a terminal status stamps two distinct ISO timestamps: `closed_at` records when the tracker mutation happened, while `completed_at` records when the work actually finished. They initially match, but a delayed close can supply `pm close <id> --completed-at <timestamp>` and a terminal item can be corrected through the governed `pm update <id> --completed-at <timestamp>` path. Reopening clears both fields, and `pm copy` strips both. Time-window context, release notes, and changelog bucketing prefer `completed_at`; legacy items disclose their compatibility path by falling back to `closed_at`, then `updated_at` only when neither lifecycle timestamp exists.
 
+`--unset` on `pm create`, `pm update` and `pm update many` clears scalar metadata fields by name. It is repeatable and also accepts a comma-separated list, so `--unset deadline,assignee --unset release` is the same as three separate flags. Each name is validated on its own: an unknown or empty part is refused by name before anything is written, including in `update many` dry runs. Field keys cannot contain commas, so the split is never ambiguous, and `pm schema add-field` refuses comma keys and flags ([pm-gh1633](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1633.toon); repository-only tracker record excluded from npm).
+
 `pm create --blocked-by <id>` and `pm update --blocked-by <id>` keep the scalar `blocked_by` field as the latest/primary blocker for compatibility. When the value resolves to a real item, the command also appends a `blocked_by` dependency edge so `pm deps` and reverse dependency scans see the full blocker graph. Repeating `pm update --blocked-by` with a different blocker preserves the prior blocker edge and appends the new one; repeating the same blocker is deduplicated. Use `pm update <id> --unset blocked-by` to clear the scalar and all `blocked_by` dependency edges.
 
 Unsupported `pm block` and `pm unblock` invocations return usage errors with
@@ -859,6 +899,19 @@ Template-defined custom type options accept string, number, and boolean defaults
 Tracker reference: [pm-l6rz](../.agents/pm/issues/pm-l6rz.toon).
 
 Use `pm close <id> "<reason>"` instead of `pm update --status closed`.
+An update that still names the close status routes through `pm close` and
+reports `auto_routed_from_update_to_close`. When the item is already closed
+with the same reason (and the same `--completed-at`, if given), the update is
+not a transition: it keeps `closed_at`, writes no closure history, and reports
+`terminal_state_unchanged` instead, even with `--force` (GH-1628). Any other
+requested fields take the ordinary update path: `updated_at` moves and a
+history entry is written only when one of them changes a stored value, so a
+request whose every field already matches leaves the item untouched. A
+different reason is a repeat closure, which still needs `--force`. A blank
+reason while `governance.require_close_reason` is enabled goes to the close
+route, which refuses it exactly as it would on an open item. If another writer
+reopens the item before the other fields are written, the request is closed
+through `pm close` as usual.
 
 ## Lifecycle Aliases
 
@@ -996,7 +1049,7 @@ pm test <id> --run --only-last
 pm test-all --status in_progress --progress
 ```
 
-Linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH` for every command and checks stored-command provenance before process creation. Direct runner binaries such as `vitest` or `node --test`, shell-wrapped equivalents, package-manager scripts, and non-Node runners are accepted consistently; prefer `node scripts/run-tests.mjs ...` when available because it also reproduces repository build, coverage, and cleanup policy. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list.
+Linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH` for every command and checks stored-command provenance before process creation. Direct runner binaries such as `vitest` or `node --test`, shell-wrapped equivalents, package-manager scripts, and non-Node runners are accepted consistently; prefer `node scripts/run-tests.mjs ...` when available because it also reproduces repository build, coverage, and cleanup policy. The two-token form `--add command "npm test -- parser"` (and `--add path "..."` / `--remove command "..."`) is accepted when the value is quoted into a single shell argument; it is normalized to `--add command=...` before parsing. Use `--add-json` when command strings contain commas, nested quotes, shell variables, or `--` separators that are awkward to preserve through CSV-style `--add` parsing. Linked tests retain append order; consequently `--only-last` always selects the most recently added stored test. `--match`, `--only-index`, and `--only-last` select which linked tests execute without mutating the stored linked-test list. When a selector skips any test, the run receipt lists only the selected entries in `tests[]`. `count` still reports the full stored collection, `selection` records the selected 1-based indexes and the skipped count, and `tests_omitted: { count, restore_with: "pm test <id> --list" }` names the read that returns every stored test. The receipt no longer repeats the selection as a warning string. On a 58-test item, an `--only-last` receipt went from 8,662 to 2,212 bytes in TOON and from 18,826 to 2,695 bytes in JSON ([pm-gh1630](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1630.toon); repository-only tracker record excluded from npm). With `--lean`, a run that passed with no context mismatch and no failure category also replaces the sandbox `execution_context` with its modes, `mismatch_detected: false`, the `trusted` boolean (a passing run can be untrusted under an explicit override), the trust reason and `restore_with: "not retained; a run without --lean reports the full context"`, and omits the all-zero `failure_categories`. The hint deliberately does not say to rerun: a rerun repeats any mutating flags of the original invocation, such as `--remove-index`. That run measured 865 bytes in TOON and 1,166 in JSON. A failure, refusal, skip or context mismatch keeps the full provenance and categories ([pm-covpax](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-covpax.toon); repository-only tracker record excluded from npm).
 
 Strict linked-test guards:
 
@@ -1182,16 +1235,21 @@ unowned hooks. Default installation remains hook-free. See
 
 ## History and Recovery
 
-Compact and provenance history without `--limit` display newest entries first,
-so the latest handoff survives an output budget. The `order` receipt declares
-the display direction and `total` counts all matching entries before limits.
-Physical `index` values and durable version addresses retain their original
-meaning. Use the returned `output_budget_truncation` continuation with
-`--output-cursor` to read older rows without gaps or duplicates. Explicit
-`--limit N` keeps the latest N entries in chronological order; `--full
---output-budget unbounded` returns complete chronological entries. Verification
-always checks the full authoritative chain
-([pm-gh1605](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1605.toon); tracker record excluded from npm).
+Compact and provenance history default to newest-first, including reads with
+`--limit`. Full entries default to oldest-first. Use `--order oldest_first` or
+`--order newest_first` to choose the same direction for any projection and its
+value diffs. `--limit N` selects the latest N matching entries before ordering.
+The `order` receipt declares direction and `total` counts matches before limits.
+Physical indices and durable versions retain their original meaning. Use
+`--output-cursor` with the returned continuation to traverse the selected order.
+Verification always checks the full authoritative chain.
+
+Compatibility: a compact/provenance latest-N read used to flip to chronological
+order. Chronological consumers should explicitly use, for example,
+`pm history pm-a1b2 --diff --limit 20 --order oldest_first`.
+Full reads keep their chronological default.
+Tracked by [pm-gh1617](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1617.toon)
+(tracker record excluded from npm).
 
 After a branch merge that touched tracker history, preview and apply the
 one-command reconciliation gate:

package/docs/CONFIGURATION.md

@@ -110,7 +110,43 @@ capture an opaque boot/PID-namespace coordinate and the owner's process start
 tick. A matching host can reclaim a provably dead original owner before TTL,
 including when its PID has been reused. Foreign hosts, legacy receipts, denied
 process probes and unavailable identity remain subject to the existing TTL
-policy. Early recovery writes an immutable `locks/recoveries/*.json` intent
+policy. A commit gate with a provably dead same-host owner can also be recovered
+immediately, before its ordinary age threshold. Its original owner receipt is
+retained in `locks/recoveries/gate-<generation-hash>/owner.json`. These nonempty
+generation directories prevent concurrent recoverers from retiring a replacement
+gate and must be retained while writers may still hold observations of that
+generation. Recovery after the age grace requires a dead PID or verified PID
+reuse for a readable owner, and uses the same retained generation protocol.
+A live PID with unavailable start identity keeps its gate regardless of age;
+elapsed time alone cannot safely distinguish a paused writer from abandonment.
+Recorded host coordinates must be verified before recovery; a recorded foreign
+host or unavailable recorded host evidence cannot be replaced by a local PID
+comparison. Legacy receipts without `host_identity` use a local PID probe after
+the grace period. On shared storage, that probe can retire a gate owned by a
+writer on another host whose PID appears dead locally; these legacy receipts
+do not provide cross-host recovery safety.
+Non-missing owner-file read errors also retain the gate regardless of age.
+Lock wait durations use a monotonic clock independently of the
+wall-clock timestamps used for TTL policy. This recovery is tracked by
+[pm-gh1609](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1609.toon)
+(repository tracker record excluded from npm).
+
+If a reboot, PID-namespace change or tracker relocation leaves an unverifiable
+`locks/<lock-file>.stale-cleanup` gate, automatic age-based recovery intentionally
+refuses it. `pm gc --scope locks` does not remove these gate directories.
+For manual recovery, first stop every CLI, MCP server, watcher and service that
+can write this tracker, including writers on other hosts when storage is shared.
+Independently establish that the recorded original owner cannot still run; a
+different host hash or an old timestamp alone is insufficient. While exclusive
+access is maintained, preserve the complete gate directory and its `owner.json`
+receipt by moving it to a unique backup location outside `locks`, without
+overwriting any existing backup. Keep `locks/recoveries` evidence intact. Then
+retry the original command, run `pm health --check-only`, and verify the affected
+item's history with `pm history <id> --verify --strict-exit`. If exclusive access
+or owner death cannot be established, retain the gate and investigate ownership.
+This procedure does not override the remaining lease's TTL or ownership checks.
+
+Early recovery writes an immutable `locks/recoveries/*.json` intent
 receipt before removal; it records the original owner and is an attempted
 recovery audit, not proof that a later mutation committed. Keep these local
 runtime receipts out of version control.
@@ -390,6 +426,16 @@ pm get <id> --full --json
 pm contracts --json
 ```
 
+With JSON output, preflight advisories are deferred until the command outcome.
+A failed command includes their stable codes in the error envelope's `warnings`
+array on stderr, preserving one parseable error and its original exit code.
+Additional explanatory or remediation text is retained in `warning_details`.
+A successful command emits one `{ "type": "warning", "warnings": [...] }`
+diagnostic on stderr when needed; its result remains on stdout. Human output
+keeps immediate warning text. See
+[pm-gh1602](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1602.toon)
+(repository tracker record excluded from npm).
+
 `--output-format json|toon` selects encoding on both reads and mutations.
 Item collection and lifecycle commands accept `--format json|toon` as a
 compatibility alias, before or after the command:
@@ -593,6 +639,7 @@ Useful commands:
 
 ```bash
 pm config project set search_default_mode keyword
+pm config project set context_next_ranking_policy weighted   # pm next: priority_floor (default) or weighted
 pm config project set search_mutation_refresh_policy cache_only
 pm config project set search_embedding_corpus_max_characters 12000
 pm config project set search_query_expansion_enabled true

package/docs/DEVELOPMENT_DEPENDENCY_SECURITY.md

@@ -130,6 +130,32 @@ patterns, absolute paths and invocation-relative anchoring remain supported.
 The regression uses a real temporary directory and the same deeply nested input
 that failed before the replacement. Audit errors remain mandatory failures.
 
+## Redirect credential and glob amplification advisories
+
+[pm-irviv0](../.agents/pm/issues/pm-irviv0.toon) tracks
+[GHSA-mrwp-f3q8-3g9p](https://github.com/advisories/GHSA-mrwp-f3q8-3g9p)
+(`follow-redirects` 1.16.0 through 1.16.1: cross-realm `sensitiveHeaders`
+arrays are discarded, so custom credentials can follow redirects) and
+[GHSA-g3hv-75wg-m249](https://github.com/advisories/GHSA-g3hv-75wg-m249)
+(`minimatch` before 11.0.1: denial of service through glob-part
+amplification). Both were published on October 30 and the registry feed
+reported them from the next run on `main` while OSV was still clean, so the
+advisory gate refused every PR and the scheduled release path until the lock
+changed. `follow-redirects` is reached only through the CodSpeed benchmark
+plugin's Axios client, and `minimatch` through ESLint and its config array
+and as a direct dependency of `@stryker-mutator/core` (mutation testing); all
+of these are development dependencies and none establishes a CLI or SDK
+route. The pnpm overrides require `follow-redirects` 1.16.2 or a newer
+1.x release and `minimatch` 11.0.1 or a newer 11.x release. `minimatch` 11
+keeps dual CommonJS and ES module exports, so ESLint's `require` path is
+unchanged and the full lint run passes; the override applies to the Stryker
+path as well. Both releases satisfy pnpm's one-day
+minimum release age without an exclusion; the seven-day Dependabot cooldown
+is unchanged. The gate's catch-all refusal said that no feed success could be
+inferred, which hid the real cause (a non-empty registry id list); read
+`.cache/dependency-security/receipt.json` before treating that message as a
+feed outage.
+
 ## CodSpeed 5.7.1 patch
 
 CodSpeed's declared dependency previously resolved Axios 1.19.0, and both

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -120,8 +120,9 @@ primary rows while a rich result can name
 `checks.0.details.missing_resolution_rows` as a continuation row. This prevents
 an inner diagnostic array from disabling `--output-limit` on the outer checks.
 `toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
-with one shared key set renders as a length-marked TOON table; mixed, nested,
-or heterogeneous arrays retain the expanded representation. Quoted,
+with one shared key set can render as a length-marked TOON table. Nested or
+heterogeneous object rows can also use a smaller table with explicit sibling
+encoding metadata; otherwise they retain the expanded representation. Quoted,
 separator-bearing, and multiline values use the canonical TOON encoder and
 round-trip through the strict decoder.
 Commands without a row collection, including a dependency tree or leaf `get`,
@@ -463,3 +464,24 @@ Continuation and compaction slice these receipts with the rows. Self-describing
 focus rows need no extra receipt. Semantic receipts are preserved during
 explanatory-string compaction, and corrupt alphabet or row-count mismatches are
 rejected.
+
+
+### Compact nested table metadata
+
+Tracked by [pm-gh1603](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1603.toon)
+(tracker record excluded from npm). The SDK `encodePmTableRows(rows, { compact: true })`
+can declare `list_columns` (column to delimiter) and `null_columns` alongside
+`json_columns` and `absent`. Omitted null columns also carry `column_order`
+to restore their original first-occurrence positions. `decodePmTableRows` restores
+these facts exactly.
+A safe string-array column uses `;` between nonempty members; an empty cell means
+an empty array. Any empty member, delimiter collision, mixed type or nested value
+uses the existing JSON-column encoding instead. Null columns are omitted only
+when every row explicitly contains null; missing fields remain distinct.
+
+The TOON host selects compact tables only when they reduce rendered bytes.
+Agenda rows therefore share null-field declarations and tag arrays avoid repeated
+JSON escaping. JSON output and SDK query results retain their original values.
+Consumers of TOON tables must honor all declared encoding metadata or use the
+current SDK decoder. Whole-envelope budgets measure the actual serialized form,
+including decoding metadata.

package/docs/PACKED_FIRST_RUN.md

@@ -6,7 +6,8 @@ Trackers: [pm-ygli86](../.agents/pm/tasks/pm-ygli86.toon),
 [pm-p5u6](../.agents/pm/chores/pm-p5u6.toon).
 
 CI globally installs one tarball in isolated npm prefixes on Ubuntu/macOS/Windows
-with Node 22.18.0 and 24, runs the installed `pm` shim, then invokes:
+with Node 22.18.0 and 24, one `Packed runtime (<os>)` job per OS with a fresh
+prefix, cache and home per Node version, runs the installed `pm` shim, then invokes:
 
 ```bash
 node scripts/release/packed-first-run.mjs /path/to/installed/@unbrained/pm-cli

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -221,12 +221,30 @@ Read-option recovery is tracked by
 use `--output-format toon|json` across read commands. Completeness uses
 `--output-include full` on list, search and get; context detail depth uses
 `--depth full`. These controls retain the normal row and token ceilings.
-When `context --full`, `list/search --depth full`, or `--toon` on list, search,
-context or get is refused,
-the error provides `recovery.suggested_retry_args` for the same command with the
-supported spelling. The SDK's `resolveReadOptionRetryArgs` exposes the same
-token-preserving correction. Conflicting controls or ambiguous operands do not
-receive a guessed retry.
+When a completeness spelling is refused on a read command that has an
+equivalent spelling of its own, the error provides
+`recovery.suggested_retry_args` for that same command. Examples are
+`get/context --brief`, which becomes `--depth brief`, and
+`list/search/history --depth full`, which becomes `--full`. The same applies to
+`--toon` on list, search, context or get, which becomes `--output-format toon`.
+The correction is derived from runtime contracts, not from a hand-maintained
+list. A boolean `--<level>` maps to `--depth <level>` only when that command's
+`--depth` flag contract declares the level in its `values` domain. A
+`--depth <level>` maps to `--<level>` only when the level is one of the
+command's declared read-output projection modes. `--depth standard` on a
+command without `--depth` replays without the flag, because standard is every
+command's default level. Aliased paths such as `deps` and `health` replay on
+their canonical noun-first path (`pm item deps`, `pm ops health`). When a
+command has no equivalent, for example `search --depth brief`, no retry is
+guessed. The refusal instead lists the controls that command accepts: for
+search, `Completeness controls accepted by pm search: --compact, --full.`
+([pm-gh1626](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1626.toon);
+repository-only tracker record excluded from npm). The SDK's
+`resolveReadOptionRetryArgs` exposes the same token-preserving correction, and
+`resolveReadCompletenessControls` returns each command's declared vocabulary.
+Conflicting controls such as `--fields`, `--output-include`, `--section`, `--for`
+or another completeness flag, and ambiguous operands, do not receive a guessed
+retry.
 An explicit `--json` conflicts with `--toon`, so that invocation receives no
 encoding-changing retry. Non-conflicting TOON refusals include the corrected
 command in human output without requiring JSON diagnostics.