@unbrained/pm-cli 2026.8.30 → 2026.9.1

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -55,7 +55,7 @@ This clones the repo, reads `.claude-plugin/marketplace.json` at the root, insta
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-Gives you the 31 MCP tools without skills or slash commands.
+Gives you the 32 MCP tools without skills or slash commands.
 
 ### 3. Direct project `.mcp.json` (project-scoped MCP only)
 
@@ -117,7 +117,7 @@ pnpm smoke:claude-plugin
 ```
 
 Verifies: plugin file structure, manifest name consistency, stateless MCP
-discovery for `2026-07-28`, 31 tools present, full workflow (init → create →
+discovery for `2026-07-28`, 32 tools present, full workflow (init → create →
 claim → update → link files/docs/tests → get → context → search → validate →
 health), and session-start hook.
 
@@ -134,8 +134,8 @@ pnpm smoke:codex-plugin
 ```bash
 pm contracts --schema-only --json
 pm contracts --command extension --flags-only --json
-pm extension --doctor --project --detail summary --strict-exit
-pm extension --reload --project
+pm package doctor --project --detail summary --strict-exit
+pm package reload --project
 ```
 
 Why this matters:
@@ -188,7 +188,7 @@ The authoritative plugin version is `plugins/pm-claude/.claude-plugin/plugin.jso
 
 The MCP server uses JSON-RPC 2.0 over stdio with canonical protocol version
 `2026-07-28`. A bounded legacy path remains for unversioned older hosts, with
-`2025-06-18` initialize available to enrich client identity; current hosts
+initialize-era handshakes available to enrich client identity; current hosts
 discover the server and send metadata on every request.
 
 ## Extension Policy Diagnostics

package/docs/COMMANDS.md

@@ -67,7 +67,7 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 | Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                                    | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
 | Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                                            | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
 
-`†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm install linked-test-adapters --project`).
+`†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm package install linked-test-adapters --project`).
 
 ## Bootstrap
 
@@ -113,21 +113,21 @@ Use `--with-packages` for one-step agent setup when bundled package commands sho
 
 ```bash
 pm package                     # bare command defaults to --explore (list installed)
-pm install '*' --project
+pm package install '*' --project
 pm package catalog --project
 pm package manage --project --output-format json
-pm install npm:@scope/pm-package --project
+pm package install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
 pm package migrate --project --dry-run --json
 pm package migrate --project --json
-pm upgrade --dry-run
-pm upgrade --packages-only
-pm upgrade --cli-only --repair
+pm package upgrade --dry-run
+pm package upgrade --packages-only
+pm package upgrade --cli-only --repair
 ```
 
-`pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
+`pm package` is the canonical package-first workflow. `pm package` and the hidden `pm extension` alias default to `--explore` on a bare invocation so agents can list installed packages without remembering an action flag. `pm package install '*'`, shell-expanded `pm package install *`, and `pm package install all` install bundled first-party packages. `pm install`, `pm upgrade`, and `pm extension` remain executable as deprecated compatibility spellings declared in `PM_COMMAND_ALIAS_CONTRACTS`; they emit a migration hint and must not appear in documentation or skills as instructions.
 `pm package catalog` emits one row per package, with every resolvable bundled
 alias preserved in `aliases`; totals therefore measure packages rather than
 alias-index entries. `pm package manage` participates in the universal read
@@ -141,7 +141,7 @@ the choice ambiguous and provides explicit bare and `npm:` retry commands.
 durable workspace-history receipts; a successful migration is skipped on later
 processes, while a failed migration remains retryable. `extension migrate` is
 the compatibility spelling.
-When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
+When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm package install calendar`, `pm package install search-advanced`, `pm package install governance-audit`, or `pm package install guide-shell`).
 
 ## Triage
 
@@ -669,7 +669,7 @@ Tracker references: [pm-72xf](../.agents/pm/features/pm-72xf.toon).
 
 ## Templates
 
-After `pm install templates --project`, `pm templates` lists both saved templates and built-in starters:
+After `pm package install templates --project`, `pm templates` lists both saved templates and built-in starters:
 
 ```bash
 pm templates
@@ -804,7 +804,7 @@ pm test <id> --run --only-last
 pm test-all --status in_progress --progress
 ```
 
-Linked test commands should be sandbox-safe. Prefer `node scripts/run-tests.mjs ...` for repo-local test suites; normal package-manager scripts such as `pnpm test` and `npm run test` are accepted because linked-test execution injects temporary `PM_PATH` and `PM_GLOBAL_PATH`. Direct runner binaries such as `vitest` or `node --test` still need the wrapper or explicit inline sandbox env. 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.
 
 Strict linked-test guards:
 
@@ -818,7 +818,7 @@ pm test <id> --run \
 
 ## Search Reindex and Eval
 
-`reindex` is provided by the `search-advanced` package (`pm install search-advanced --project`).
+`reindex` is provided by the `search-advanced` package (`pm package install search-advanced --project`).
 
 ```bash
 pm reindex --mode keyword
@@ -1240,7 +1240,7 @@ only after selecting the exact path.
 
 ## Completion
 
-`pm completion` is provided by the optional `guide-shell` package (`pm install guide-shell --project`).
+`pm completion` is provided by the optional `guide-shell` package (`pm package install guide-shell --project`).
 
 ```bash
 pm completion bash

package/docs/CONFIGURATION.md

@@ -210,7 +210,7 @@ Markdown item files are treated as legacy migration input only. Mutations always
 Most commands default to sparse TOON:
 
 ```bash
-pm list-open --limit 10
+pm list --status open --limit 10
 ```
 
 Use JSON for strict machine parsing:

package/docs/CONTEXT_RECOVERY_PRIMITIVES.md

@@ -46,11 +46,20 @@ When multiple entries exist, the SDK selects the requested package by key or `na
 
 ## History and merge recovery
 
-History hash capability 3 distinguishes the current canonical writer surface from older epoch-2 writers while retaining readers for epochs 1 and 2. An unsupported epoch is version skew, not permission to reinterpret or silently normalize history.
-
-Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes also carry the current item-hash capability, so a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
-
-Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed.
+History hash capability 3 distinguishes the current canonical writer surface
+from older writers while retaining frozen readers for epochs 1 and 2. Two
+writer surfaces were historically emitted under epoch 2: its earlier form
+excluded linked-test workspace/provenance fields and test-run execution
+receipts while normalizing dependency ids; its later form included those
+fields. Verification recognizes both immutable forms and requires each entry's
+before/after hashes to use one consistent form. Current-document verification
+selects the candidate that matches the verified chain head. An unsupported
+epoch is version skew, not permission to reinterpret or silently normalize
+history.
+
+Health keeps the metadata-only cache path for clean history streams. A cached hash mismatch, chain mismatch, or writer-version skew is only a candidate: health rereads canonical item sources and verifies stream content hashes before reporting corruption. The `history_drift` details expose `cache_confirmation` candidate, confirmed, and resolved-false-positive item sets, while `cache_hit_verification: metadata_then_content_hash` identifies the authoritative fallback. Drift-cache envelopes carry both their schema version and the current item-hash capability, so changing legacy canonicalization invalidates prior verdicts and a runtime with incompatible hash semantics rebuilds the cache instead of trusting it.
+
+Merge reconciliation may consume a durable hash-only receipt without `--force` only when its canonical item path, complete declared-field set, and every merged-value hash exactly match the current item snapshot. Raw discarded values remain clone-local. Any incomplete or mismatched proof fails closed. SDK gates use `inspectMergeReceiptEvidence` or `runMergeReceiptEvidenceReport` to retain the distinction between no evidence, rejected evidence, and clone-local evidence whose Git directory could not be resolved; `clone_local_evidence_resolved=false` makes the loss-aware report incomplete. The list-only and legacy report compatibility projections intentionally return valid receipts only. Diverged history unions also fail closed when deterministic suffix ordering would make any patch operation inapplicable, instead of publishing a rehashed stream with a skipped branch effect.
 
 ## Strict-create recovery
 

package/docs/DEFECT_RECURRENCE.md

@@ -79,6 +79,8 @@ The repository example is [config/defect-recurrence-policy.json](../config/defec
 
 Repository policy validation rejects duplicate ids, absent historical examples, missing family negative controls, invalid taxonomy values, and budgets outside zero through one. Deterministic sorting makes the serialized policy merge-friendly.
 
+Register a family whenever a defect is recorded as a recurrence of an earlier one, meaning the new item carries a `recurs_from` edge to its predecessor. A recurrence with no family produces no local and no hosted protection, so the next instance is rediscovered by hand. Coverage of recorded recurrence lineages is not yet computed by any gate; that gap is tracked on [pm-7c27ep](../.agents/pm/issues/pm-7c27ep.toon).
+
 ## Defect Evidence on PM Items
 
 Projects can register the structured fields without changing the SDK:

package/docs/MCP_2026_07_28.md

@@ -12,7 +12,9 @@ by [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
 [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
 [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon). Skills and Apps are tracked
 by [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon) and
-[pm-pznhee](../.agents/pm/features/pm-pznhee.toon).
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon). Progressive tool discovery
+and canonical model-facing results are tracked by
+[pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 Status: accepted. MCP `2026-07-28` is pm's canonical protocol revision.
 
@@ -39,15 +41,37 @@ capabilities, public cache policy, server identity, and bounded instructions.
 No modern request reads identity, capabilities, or version from a previous
 request.
 
+The optional `dev.unbrained.pm/progressive-tool-discovery` extension is also request-local. Negotiated clients receive a stable five-tool entry catalog and expand it with `pm_discover`; unnegotiated clients retain the complete profile-selected list. Negotiated tool results designate `structuredContent.result` as canonical and use text content only as a pointer, while the isolated compatibility adapter retains duplicated JSON text for existing clients. The public SDK owns ranking, cursor binding, token and omission receipts, and cache invalidation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 ## Legacy boundary
 
-The sole supported legacy revision is `2025-06-18`, accepted through the
-existing stdio adapter. Unversioned requests stay on this legacy path because
-they cannot claim the current revision; `initialize` enriches their client
-identity but is not required for compatibility with older pm hosts. The
-adapter has no session id, does not affect modern requests, and is excluded
-from `server/discover`'s `supportedVersions` because it cannot be selected
-through modern per-request metadata.
+Legacy means every revision that establishes a session with an `initialize`
+handshake, which the canonical revision defines as `2025-11-25` and earlier.
+The stdio adapter therefore accepts the full initialize-era set, newest first:
+
+| Revision     | Accepted at `initialize` | Notes                                                                |
+| ------------ | ------------------------ | -------------------------------------------------------------------- |
+| `2025-11-25` | yes                      | Final legacy revision; offered when a client omits `protocolVersion` |
+| `2025-06-18` | yes                      | Earlier legacy revision retained for existing consumers              |
+
+`initialize` answers with the revision the client requested, because a legacy
+client has no fall-forward mechanism and treats the answered version as the
+negotiated one. A revision outside the set is refused with `-32022` and the
+refusal names every supported revision, since that error text is the only
+diagnostic such a client can surface.
+
+`PM_MCP_LEGACY_PROTOCOL_VERSIONS` on the public SDK surface is the single
+declaration of this set. The plugin MCP smoke gate reads it from the built SDK
+and drives one real `initialize` per declared revision against the released
+launcher, plus a negative control for an undeclared revision, so the accepted
+set and the documented set cannot drift apart.
+
+Unversioned requests stay on this legacy path because they cannot claim the
+current revision; `initialize` enriches their client identity but is not
+required for compatibility with older pm hosts. The adapter has no session id,
+does not affect modern requests, and is excluded from `server/discover`'s
+`supportedVersions` because it cannot be selected through modern per-request
+metadata.
 
 The adapter is scheduled for removal only after published-client telemetry and
 release probes show no required legacy consumers for two consecutive release
@@ -58,7 +82,7 @@ windows. Removal is a reviewed compatibility change, never a history rewrite.
 - Stdio modern clients call `server/discover` with current request metadata,
   then send the same version and capability keys on every request.
 - Stdio legacy clients retain their existing response shapes and may use
-  `initialize` with `2025-06-18` to supply client identity.
+  `initialize` with any accepted legacy revision to supply client identity.
 - Streamable HTTP requires `MCP-Protocol-Version` and `Mcp-Method` on every
   request. `Mcp-Name` is required only for `prompts/get`, `resources/read`, and
   `tools/call`; other methods omit it. Schema-declared `x-mcp-header` values are

package/docs/MCP_2026_07_28_CONFORMANCE.md

@@ -13,6 +13,7 @@ evidence or an explicit open obligation.
 | Header mismatch `-32020` and missing capability `-32021`                                           | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented in SDK, stdio, and Streamable HTTP                                                                            | SDK negative controls and `tests/integration/mcp-streamable-http.spec.ts`                 |
 | Required result `resultType`; legacy omission means complete only at compatibility boundary        | [pm-vae5ec](../.agents/pm/features/pm-vae5ec.toon)  | Implemented for modern pm results                                                                                        | SDK unit and modern direct-server tests                                                   |
 | No modern initialize, initialized notification, ping, or protocol session                          | [pm-sqvshj](../.agents/pm/decisions/pm-sqvshj.toon) | Implemented with bounded legacy stdio adapter                                                                            | modern removed-method and legacy handshake tests                                          |
+| Legacy interoperability covers every initialize-era revision the spec names   | [pm-edywqn](../.agents/pm/issues/pm-edywqn.toon)   | Implemented: `2025-11-25` and `2025-06-18` accepted, requested revision echoed                                            | `tests/integration/mcp-handshake.spec.ts` handshake matrix plus the plugin smoke `assertProtocolHandshakeMatrix` real-process gate and its negative control |
 | MRTR `input_required`, retry state, and reverse-request removal                                    | [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon)  | Implemented for SDK and stateless stdio adapter                                                                          | `tests/unit/sdk/mcp/interactions.spec.ts`; direct server negative controls                |
 | `subscriptions/listen`, request-scoped streams, no SSE resumability                                | [pm-v7e337](../.agents/pm/features/pm-v7e337.toon)  | Implemented locally; packed and published proof follows merge                                                            | subscription SDK, stdio, HTTP, backpressure, disconnect, and retry tests                  |
 | Official `io.modelcontextprotocol/tasks` extension                                                 | [pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon)  | Implemented for eligible tool calls, durable lifecycle, and stdio methods; notifications remain with subscriptions owner | `tests/unit/sdk/mcp/tasks.spec.ts`, `tests/integration/mcp-stateless-protocol.spec.ts`    |

package/docs/MCP_CAPABILITY_SURFACES.md

@@ -1,6 +1,6 @@
 # Runtime capability surfaces
 
-Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon)
+Tracker: [pm-xwah](../.agents/pm/chores/pm-xwah.toon), [pm-kxci8x](../.agents/pm/tasks/pm-kxci8x.toon), [pm-mu8m](../.agents/pm/tasks/pm-mu8m.toon), [pm-9k90](../.agents/pm/features/pm-9k90.toon), [pm-m4ikkz](../.agents/pm/features/pm-m4ikkz.toon), [pm-yf07b7](../.agents/pm/features/pm-yf07b7.toon), and [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
 
 The SDK exports one agent capability contract for command visibility, MCP tool profiles, resources, and workflow prompts. CLI-facing generators and MCP hosts should project from these contracts instead of maintaining independent allowlists.
 
@@ -15,6 +15,12 @@ Set `PM_MCP_PROFILE` for the `pm-mcp` process:
 
 An activated extension command makes `pm_run` discoverable outside a custom profile. Its action is added to the live `pm_run` action enumeration. Custom profiles remain exact allowlists.
 
+## Progressive discovery
+
+Modern clients may negotiate `dev.unbrained.pm/progressive-tool-discovery`. Their initial `tools/list` response is the stable five-tool entry catalog, and `pm_discover` expands authorized tools by intent, family, and tier under explicit row and token ceilings. Unnegotiated and initialize-era clients retain the full selected profile.
+
+The SDK ranks with visible lexical, semantic, graph, permission, freshness, and usage signals, binds cursors to all ranking inputs, and emits omission recovery plus cache invalidation metadata. Negotiated tool calls make `structuredContent.result` canonical and replace duplicated JSON text with a pointer; compatibility clients retain the old representation. See [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md).
+
 Package authors can declare `tier: "core" | "standard" | "full" | "internal"` on `registerCommand()` definitions. The default is `standard`; `internal` commands remain callable by native dispatch but are not advertised by normal MCP profiles.
 
 ## Workspace schema projection

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -1,13 +1,14 @@
 # MCP Remote Transport, Authorization, and Migration
 
-Tracker references: [pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
+Tracker references: [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon),
+[pm-v7e337](../.agents/pm/features/pm-v7e337.toon),
 [pm-3zh9s4](../.agents/pm/features/pm-3zh9s4.toon), and
 [pm-vzcisw](../.agents/pm/chores/pm-vzcisw.toon).
 
 pm exposes the same MCP 2026-07-28 dispatcher through two adapters:
 
 - `pm-mcp` is the local JSON-RPC/stdio process. It retains a bounded
-  `2025-06-18` compatibility adapter for existing local consumers.
+  initialize-era compatibility adapter for existing local consumers.
 - `pm-mcp-http` is the canonical sessionless Streamable HTTP POST process. It
   accepts only modern request-local protocol metadata and never creates an
   MCP session.
@@ -36,6 +37,7 @@ Configuration is explicit and environment-only:
 | `PM_MCP_HTTP_AUTH_ISSUER`     | Exact HTTPS authorization-server issuer             | none               |
 | `PM_MCP_HTTP_RESOURCE`        | Canonical MCP resource/audience URI                 | none               |
 | `PM_MCP_HTTP_SCOPES`          | Space-separated consent scopes                      | `pm:read pm:write` |
+| `PM_MCP_DISCOVERY_CURSOR_KEY` | Shared 32-byte-or-longer secret for discovery pages | process-local key  |
 
 A non-loopback bind fails closed unless token, issuer, and resource are all
 present. Production deployments should normally call
@@ -50,9 +52,17 @@ placing a real credential in documentation:
 PM_MCP_HTTP_BEARER_TOKEN='<deployment-secret>' \
 PM_MCP_HTTP_AUTH_ISSUER='https://auth.example.test' \
 PM_MCP_HTTP_RESOURCE='http://127.0.0.1:3000/mcp' \
+PM_MCP_DISCOVERY_CURSOR_KEY='<32-byte-or-longer-random-secret>' \
 pm-mcp-http
 ```
 
+Single-process deployments may omit the discovery cursor key. That selects a
+random process-local HMAC key and deliberately makes pagination process-affine:
+a restart or another worker rejects the cursor as stale. Multi-worker or
+restart-continuous deployments must provide the same high-entropy value to
+every worker. Rotating it invalidates outstanding discovery cursors without
+exposing the key in MCP input, output, errors, traces, or cache identities.
+
 The adapter serves RFC 9728 protected-resource metadata at both
 `/.well-known/oauth-protected-resource` and the path-qualified
 `/.well-known/oauth-protected-resource/mcp` location.
@@ -155,7 +165,9 @@ an unlisted source path cannot create that exemption. Any canonical match for a
 removed method, session header, SSE resume mechanism, legacy
 resource-subscription method, or deprecated server policy fails the gate.
 
-The compatibility adapter supports only protocol `2025-06-18` on local stdio.
+The compatibility adapter supports the initialize-era revisions declared by
+`PM_MCP_LEGACY_PROTOCOL_VERSIONS` (`2025-11-25` and `2025-06-18`) on local
+stdio.
 It may be removed after telemetry and installed-consumer probes show no
 required legacy clients for two consecutive release windows. Deprecated
 2026-07-28 fields remain available only where the normative registry requires

package/docs/MERGE_SAFETY.md

@@ -97,7 +97,20 @@ pm merge report
 pm merge report --include-reconciled
 ```
 
-The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `installMergeFence`, `findGitWorkspaceRoot`, `runMergeReconcile`, `runMergeReceiptReport`, `listMergeReceipts`, `auditMergeDriverConfiguration`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. `installMergeFence` accepts explicit tracker and workspace roots, so custom init hosts do not depend on process cwd or CLI globals.
+The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `installMergeFence`, `findGitWorkspaceRoot`, `runMergeReconcile`, `runMergeReceiptReport`, `runMergeReceiptEvidenceReport`, `inspectMergeReceiptEvidence`, `listMergeReceipts`, `auditMergeDriverConfiguration`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. `installMergeFence` accepts explicit tracker and workspace roots, so custom init hosts do not depend on process cwd or CLI globals.
+
+`listMergeReceipts` is the compatibility projection for callers that only need
+validated receipts. It cannot distinguish an empty evidence store from a store
+whose candidates were all rejected. Gates and diagnostic integrations should
+use `inspectMergeReceiptEvidence`, whose `invalid_evidence_count` preserves
+that distinction without returning malformed contents.
+`runMergeReceiptEvidenceReport` and `pm merge report --json` expose the same
+loss-aware contract through `complete`, `invalid_evidence_count`, and
+`clone_local_evidence_resolved`; the CLI
+exits nonzero when evidence is incomplete, even when the valid-receipt count is
+zero. Current SDK implementations always emit the new field, while its optional
+type preserves structural compatibility for existing typed adapters and test
+fixtures. `runMergeReceiptReport` remains the compatible valid-only report.
 
 ## Cross-branch id collision safety
 
@@ -189,7 +202,22 @@ pm merge reconcile --dry-run --json
 
 `history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
 
-History events now declare an item-hash epoch. The current epoch preserves linked-test insertion order; unversioned streams are verified against both the legacy sorted-test canonicalization and the order-preserving canonicalization. An unknown explicit epoch is reported as `unsupported_item_hash_version` and repair refuses to guess. This keeps version incompatibility distinct from item corruption and is tracked by [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon).
+History events now declare an item-hash epoch. Epochs are immutable writer
+contracts, not aliases for the current item serializer: epoch 1 sorts linked
+tests; epoch 2 preserves their insertion order and has both an earlier
+field-frozen form and a later expanded form because the writer surface grew
+before the marker advanced; epoch 3 is the current form. Verification accepts
+both recorded epoch-2 forms without allowing one entry to mix them, and repair
+preserves the form evidenced by each event. Unversioned streams are verified
+against the supported legacy canonicalizations. Current-document comparison
+selects the resolved epoch candidate that matches the chain head. A union merge
+may consume suffixes written by both epoch-2 forms, but its synthesized output
+uses one form for the complete re-anchored stream so every stored `after_hash`
+is exactly the next stored `before_hash`. An unknown explicit epoch is
+reported as `unsupported_item_hash_version` and repair refuses to guess. This
+keeps version incompatibility distinct from item corruption and is tracked by
+[pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon) and
+[pm-2qahia](../.agents/pm/issues/pm-2qahia.toon).
 
 ## Delete versus modify policy
 

package/docs/ONBOARDING.md

@@ -43,7 +43,7 @@ pm context --limit 10
 pm search "<request keywords>" --limit 10
 pm list --status open --limit 20
 pm list --status in_progress --limit 20
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide workflows
 ```
 

package/docs/OUTPUT_TOKEN_ACCOUNTING.md

@@ -1,6 +1,6 @@
 # Output Token Accounting
 
-Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
+Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon), [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.toon), [pm-8pnj](../.agents/pm/features/pm-8pnj.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), and [pm-jjqyzd](../.agents/pm/issues/pm-jjqyzd.toon).
 
 ## Agent Quick Context
 
@@ -39,7 +39,9 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 ## Release-Level Task Entitlement
 
-[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its five complete workflows cover:
+[`agent-task-transcripts.json`](agent-task-transcripts.json) is the SDK-validated, versioned golden corpus. [`agent-task-token-baseline.json`](agent-task-token-baseline.json) is its externally shipped release ratchet. The gate executes the built CLI against independent, identically seeded accounting-on and accounting-off workspaces. Its eight complete workflows cover:
+
+- three equivalent cold-start protocols and a fail-closed rule that the documented canonical protocol must remain the measured winner: `context --for orient` at 1,055 estimated tokens, the historical four-read sequence at 2,293, and `contracts --summary` plus `next` at 4,798 on the fixed 101-item corpus;
 
 - bounded triage, scaled-workspace orientation, and returning-agent inspection;
 - a closed-domain refusal followed by the exact advertised shell-free retry;
@@ -49,7 +51,7 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 Every step verifies its public SDK output family, canonical successful or refusal exit status, required own-property paths, declared `expected_field_values`, and refusal identity where applicable. Recovery steps must declare a successful output family instead of chaining one refusal to another, every refusal in a completed task must have a later successful `recovery_for` step, and every completed task must terminate with successful output. Successful steps cannot carry refusal-only metadata. Dot-separated `required_fields` and `expected_field_values` paths are traversed structurally from the output root, so incidental prose or nested key names cannot satisfy completeness or terminal-state assertions. The report publishes bytes and estimated tokens for each step and completed task, retry counts, corpus digest, and composite cost. Accounting-on application payloads must be byte-equivalent to their independently captured accounting-off payloads after removing only the receipt. Receipt byte and token fields are independently measured rather than trusted. Runtime refusals verify that their self-reported `total_bytes` matches the independent transport and that `total_estimated_tokens` equals `ceil(total_bytes / 4)`; Commander usage refusals that happen before accounting attachment are measured directly from the captured transport and labeled `independent_transport`.
 
-The baseline fails closed on corpus digest, task identity, step identity, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
+The baseline fails closed on corpus digest, task identity, step identity, the canonical orientation winner and its ceiling, missing or non-finite per-step and per-task ceilings, and missing or non-finite composite cost ceilings. A seeded million-token completed-task regression proves the ratchet fails. Run it with:
 
 ```bash
 pnpm quality:agent-task-token

package/docs/PROGRESSIVE_TOOL_DISCOVERY.md

@@ -0,0 +1,42 @@
+# Progressive Tool Discovery
+
+Tracker: [pm-3g3f8z](../.agents/pm/features/pm-3g3f8z.toon).
+
+`pm` exposes a public SDK discovery engine and an opt-in MCP extension for large tool catalogs. The design keeps the full legacy-compatible catalog available while allowing capable clients to attach only a small entry surface and expand it by intent.
+
+## Negotiation and entry catalog
+
+`server/discover` advertises the namespaced `dev.unbrained.pm/progressive-tool-discovery` extension. A client opts in by returning that extension in the request-local MCP capabilities on every modern request. Negotiated `tools/list` responses contain the stable entry catalog:
+
+- `pm_discover` for bounded capability expansion;
+- `pm_next` and `pm_context` for action and workspace orientation;
+- `pm_search` and `pm_get` for targeted retrieval.
+
+Clients that do not negotiate the extension receive the complete profile-selected tool list. Legacy initialize-era clients are unchanged.
+
+## Public SDK contract
+
+`discoverPmTools()` accepts an authorization-filtered candidate catalog plus query, family, tier, limit, cursor, schema projection, profile, output-budget, and optional host-owned cursor-integrity-key options. It returns:
+
+- deterministic score-then-name ordering;
+- lexical, semantic, graph, permission, freshness, and usage scores with public weights and source provenance;
+- a tamper-evident cursor bound to query, filters, schemas, authorization-filtered catalog, ranking inputs, and either the private discovery process or an explicit shared host key;
+- exact estimated token cost and a fail-closed `within_budget` verdict;
+- explicit schema, row-limit, and token-budget omission receipts with recovery;
+- a private cache key, 30-second TTL, and named invalidation events.
+
+Hosts may supply normalized semantic, graph, freshness, and usage signals. Missing host values use documented deterministic fallbacks, and the result identifies every signal source; the formula never changes implicitly.
+
+SDK hosts that route pages across processes or restarts must pass the same random, secret `cursorIntegrityKey` of at least 32 bytes on every call. Omitting it deliberately selects a random process-local key: that securely enforces process affinity, and a cursor reaching another process fails closed as stale. The bundled MCP adapter reads the shared key from `PM_MCP_DISCOVERY_CURSOR_KEY`; local stdio needs no override, while multi-worker or restart-continuous HTTP deployments must configure one shared high-entropy value.
+
+## Canonical tool results
+
+Negotiated clients treat `structuredContent.result` as the single canonical model-facing application result. The text content becomes a stable pointer instead of a second JSON serialization. Errors use the same rule through `structuredContent`.
+
+Unnegotiated and legacy clients retain the prior duplicated JSON text plus structured result. That compatibility behavior is isolated at the MCP adapter boundary; domain operations and SDK results do not branch on transport generation.
+
+## Scale and change safety
+
+The discovery quality gate exercises selection, deterministic pagination, stale-cursor refusal, permission filtering, schema recovery, and token ceilings at 100, 1,000, and 10,000 candidate tools. Contract snapshots cover the tool schema, and modern MCP integration tests prove both negotiated and compatibility modes.
+
+Any tool-definition, workspace-extension, profile, authorization, ranking-signal, or cursor-key change invalidates prior cursors and cache entries. Process-local cursors also expire when that process exits. Clients restart discovery without a cursor after an explicit stale-cursor refusal.

package/docs/README.md

@@ -7,7 +7,7 @@ This directory is the public documentation home for `pm-cli`. It is organized fo
 `pm guide` is provided by the optional `guide-shell` package. Install it when local in-CLI documentation routing is useful:
 
 ```bash
-pm install guide-shell --project
+pm package install guide-shell --project
 pm guide
 pm guide quickstart
 pm guide commands --depth standard
@@ -45,6 +45,7 @@ pm guide release --json
 - [Package SDK Contract Conformance](PACKAGE_SDK_CONTRACT_CONFORMANCE.md) - authoritative public types, `typeof` module derivation, and the first-party parity gate.
 - [SDK Action and Boundary Conformance](SDK_ACTION_CONFORMANCE.md) - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
 - [MCP 2026-07-28 Protocol Decision](MCP_2026_07_28.md) - stateless request metadata, discovery, result envelopes, explicit legacy boundary, and migration policy.
+- [Progressive Tool Discovery](PROGRESSIVE_TOOL_DISCOVERY.md) - opt-in bounded MCP catalogs, public SDK ranking and pagination, canonical results, and compatibility isolation.
 - [MCP 2026-07-28 Conformance Matrix](MCP_2026_07_28_CONFORMANCE.md) - official revision changes mapped to canonical owners and executable evidence.
 - [MCP Interaction and Task SDK](SDK_MCP_INTERACTIONS.md) - public MRTR continuation, cache/schema validation, and durable task-store contracts.
 - [MCP Skills and Apps](MCP_SKILLS_AND_APPS.md) - negotiated draft workflow discovery, stable interactive views, digests, provenance, accessibility, and trust boundaries.
@@ -72,6 +73,7 @@ pm guide release --json
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context and Evidence Contracts](SDK_CONTEXT_EVIDENCE_CONTRACTS.md) - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
+- [Workspace Position and Lifecycle Roles](WORKSPACE_POSITION_AND_LIFECYCLE.md) - role-safe custom workflows plus one bounded merge-fence, receipt, history-drift, and next-action SDK read.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -144,7 +144,7 @@ consumer therefore cannot interpret the missing command or action arrays as a
 successful empty contract.
 
 ```bash
-pm list-open --output-include id,title,status --output-limit 10
+pm list --status open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
 pm search "runtime contracts" --output-limit 5 --output-format json
 pm stats --output-row-contract

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -129,7 +129,7 @@ pm reindex --mode hybrid
 If the command is absent, recovery is a two-step executable sequence:
 
 ```bash
-pm install search-advanced --project
+pm package install search-advanced --project
 pm reindex --mode hybrid
 ```
 

package/docs/SDK.md

@@ -137,7 +137,7 @@ List consumers can inspect `LIST_COMMAND_DEFAULT_PROJECTIONS` instead of
 copying command-specific defaults. Every compact or field-projected list result
 now echoes the applied `projection`; `brief` remains distinct from `compact`,
 and `DEFAULT_COMPACT_LIST_FIELDS` / `BRIEF_LIST_FIELDS` provide the canonical
-field sets. `pm contracts --command list-open --flags-only --json` includes the
+field sets. `pm contracts --command list --flags-only --json` includes the
 same per-command projection surface.
 
 ### Public-surface compatibility
@@ -336,7 +336,7 @@ Command/action contract exports:
 - Annotation and relationship option/result contracts: `CommentsCommandOptions` / `CommentsResult`, `NotesCommandOptions` / `NotesResult`, `LearningsCommandOptions` / `LearningsResult`, `FilesCommandOptions` / `FilesResult`, `FilesDiscoverOptions` / `FilesDiscoverResult`, `DocsCommandOptions` / `DocsResult`, `DepsCommandOptions` / `DepsResult`, `AppendCommandOptions` / `AppendResult`
 - Annotation kernel primitives: `resolveAnnotationInput`, `runAnnotationCommand`, `resolveAnnotationIndex`, `parseAnnotationTextInput`, `limitAnnotationEntries`, `readAnnotationEntries`, `wrapOwnershipConflict`, `isErrnoError`, and their typed input/config/result contracts
 - Linked-resource kernel primitives: `runFiles`, `runFilesDiscover`, `runDocs`, `runDeps`, `runLinkedArtifacts`, `assertLinkedArtifactMutationIsUnambiguous`, parsing/normalization/path-validation helpers, and their typed contracts. The CLI files/docs/deps modules are presentation-only re-exports of these SDK implementations. A transaction that resolves one path into both its add and remove sets fails before item or history mutation; split an intentional replacement into two commands so its context remains explicit.
-- Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
+- Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list --status blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
 - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
 - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
 - Built-in `recurs_from` records that the source is a later occurrence of the target. Its registry contract is directed, `source_after_target`, non-ordering, many-to-many, and persistent across terminal lifecycle states. Local mutation paths enforce strictly later source `created_at` metadata before item or history persistence and return structured source/target evidence when chronology is equal, reversed, or unverifiable. It therefore connects an incident family for traversal and analytics without reclassifying `supersedes` replacements or `duplicate_of` identity collapse.
@@ -1642,7 +1642,7 @@ const certified = certifyCompleteListResult(candidate);
 
 `PmCompleteListValidationError.receipt` lists every failed invariant and carries
 the exact recovery command
-`pm list-all --full --strict-read --no-truncate --output-budget unbounded --json`.
+`pm list --all --full --strict-read --no-truncate --output-budget unbounded --json`.
 The helper never infers completeness from a large limit: derived-index reads,
 terminal-state filtering, duplicate ids, cursor/session projection, compaction,
 and any omission receipt all prevent certification.