@unbrained/pm-cli 2026.8.25 → 2026.8.27

package/docs/MCP_REMOTE_TRANSPORT_SECURITY.md

@@ -0,0 +1,180 @@
+# MCP Remote Transport, Authorization, and Migration
+
+Tracker references: [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.
+- `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.
+
+The public `@unbrained/pm-cli/sdk` entrypoint owns subscription filtering,
+HTTP header projection, authorization discovery and validation, issuer-keyed
+credentials, bearer enforcement, and trace-context isolation. Adapters remain
+thin bindings over those contracts.
+
+## Run the HTTP adapter
+
+The safe default binds only `127.0.0.1:3000`:
+
+```bash
+pm-mcp-http
+```
+
+Configuration is explicit and environment-only:
+
+| Variable                      | Meaning                                             | Default            |
+| ----------------------------- | --------------------------------------------------- | ------------------ |
+| `PM_MCP_HTTP_HOST`            | Bind host                                           | `127.0.0.1`        |
+| `PM_MCP_HTTP_PORT`            | Bind port, including `0` for an ephemeral test port | `3000`             |
+| `PM_MCP_HTTP_ALLOWED_ORIGINS` | Comma-separated exact browser origins               | none               |
+| `PM_MCP_HTTP_BEARER_TOKEN`    | Opaque deployment token for the bundled verifier    | none               |
+| `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` |
+
+A non-loopback bind fails closed unless token, issuer, and resource are all
+present. Production deployments should normally call
+`createPmMcpHttpServer()` with an OAuth access-token verifier backed by their
+authorization server instead of using the executable's single opaque-token
+bootstrap verifier.
+
+For example, this starts a deliberately local protected endpoint without
+placing a real credential in documentation:
+
+```bash
+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-http
+```
+
+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.
+
+## Stream and header contract
+
+Every HTTP request is a POST to `/mcp` and negotiates both
+`application/json` and `text/event-stream`. Normal finite requests return
+JSON. `subscriptions/listen` returns an SSE response whose first message is
+`notifications/subscriptions/acknowledged`; every later subscription
+notification carries the listen request's JSON-RPC id in
+`io.modelcontextprotocol/subscriptionId`.
+
+The supported opt-ins are tool-list, prompt-list, resource-list, and exact
+resource-update notifications. Each stream serializes writes and drops a sink
+that fails or remains backpressured beyond the bounded write deadline; tool
+calls do not await subscriber delivery. Disconnecting deletes the
+request-scoped subscription. A broken stream has no replay cursor: there are no
+SSE event ids and `Last-Event-ID` is rejected. The caller retries the lost
+operation with a new JSON-RPC request id.
+
+`MCP-Protocol-Version` and `Mcp-Method` are built and validated against every
+JSON-RPC request body. `Mcp-Name` is required only for `prompts/get`,
+`resources/read`, and `tools/call`; methods such as `tools/list` omit it. Tool
+properties may declare `x-mcp-header` in their JSON Schema; the SDK validates
+the header name, rejects reserved or duplicate mappings, encodes non-ASCII and
+ambiguous values with the MCP Base64 sentinel, and compares the decoded header
+with the argument value before dispatch. CR/LF and control-character values
+are always rejected.
+
+Current pm handlers do not emit request progress or deprecated MCP log-message
+notifications. A `progressToken` or request-local
+`io.modelcontextprotocol/logLevel` is therefore never promoted to a shared
+subscription. Work that returns a durable task remains observable through the
+task lifecycle; remote operational logging belongs in the deployment's
+OpenTelemetry pipeline.
+
+## Authorization lifecycle
+
+Remote hosts can compose the public SDK primitives into a complete OAuth
+client/resource lifecycle:
+
+1. Build or read protected-resource metadata and choose an advertised
+   authorization-server issuer.
+2. Probe OAuth and OpenID discovery URLs in the specified order. Require the
+   metadata `issuer` to match exactly and require S256 PKCE.
+3. Prefer a pre-registered client, then a validated Client ID Metadata
+   Document, then bounded Dynamic Client Registration, and finally explicit
+   user-supplied registration.
+4. Validate a returned `iss` when present or advertised, bind stored
+   credentials to the exact issuer, and never reuse them across issuers.
+5. Request only the scopes needed for the operation. The resource verifies
+   bearer location, issuer, audience, and every required consent scope before
+   MCP dispatch.
+6. Replace an issuer's stored credential after refresh. Delete only that
+   issuer's entry on revocation, invalid grant, or re-registration; discovery
+   and consent then run again without affecting other issuers.
+
+`PmMcpIssuerCredentialStore` deliberately provides cloned `set`, `get`, and
+`delete` operations rather than owning token refresh network traffic. This
+keeps refresh, revocation, persistence encryption, and user interaction in the
+host that owns the authorization relationship.
+
+## Trace and privacy boundary
+
+Modern request `_meta` may carry W3C `traceparent`, `tracestate`, and baggage.
+The SDK validates syntax and byte bounds, drops every baggage member that is
+not on the host-provided allowlist, and stores the resulting context in an
+`AsyncLocalStorage` scope for only that request. Concurrent requests cannot
+inherit one another's trace context. Raw bearer tokens are hashed for
+constant-time comparison by the bundled verifier and are never included in
+claims, errors, traces, or JSON-RPC result data.
+
+| Threat                         | Enforced boundary                                                               |
+| ------------------------------ | ------------------------------------------------------------------------------- |
+| DNS rebinding/browser drive-by | Loopback default plus exact `Origin` allowlist                                  |
+| Token passthrough              | Bearer is verified at pm and never forwarded to another service                 |
+| Issuer mix-up                  | Exact discovery/response issuer checks and issuer-keyed credentials             |
+| Confused audience              | Exact protected-resource audience check                                         |
+| Excess authority               | Required-scope intersection before dispatch                                     |
+| Query/log credential leak      | Query tokens rejected; challenges and errors omit token material                |
+| Header injection               | Schema-derived allowlist, reserved-name checks, control-byte rejection          |
+| Trace privacy leak             | Syntax/size validation, baggage-key allowlist, request-local storage            |
+| Proxy cache disclosure         | MCP and metadata errors use explicit content types; MCP results use `no-store`  |
+| Replay after disconnect        | No session, event id, resume cursor, or redelivery; retry uses a new request id |
+
+## Deprecated-feature inventory and sunset
+
+Run the generated ratchet locally or in CI:
+
+```bash
+pnpm quality:mcp-deprecations
+```
+
+The inventory classifies every match as canonical source, the isolated legacy
+adapter, migration documentation, a negative control, or
+`bounded_source_control`. The last disposition applies only to exact,
+single-use source lines in the reviewed fixed allowlist; an adjacent marker or
+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.
+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
+its minimum compatibility period; no pm sunset occurs earlier than
+2027-07-28. A removal is always a reviewed release change with packed and
+published consumer proof.
+
+## Verification
+
+Focused release evidence is reproducible with:
+
+```bash
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/subscriptions.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/transport.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/sdk/mcp/authorization.spec.ts
+node scripts/run-tests.mjs test -- tests/integration/mcp-streamable-http.spec.ts
+node scripts/run-tests.mjs test -- tests/unit/scripts/release/mcp-deprecation-gate.spec.ts
+pnpm quality:mcp-deprecations
+```
+
+The full release gates, packed artifact probes, installed `npx`/`bunx`
+consumers, and published artifact checks remain distinct closeout evidence.

package/docs/MCP_SKILLS_AND_APPS.md

@@ -0,0 +1,107 @@
+# MCP Skills and Apps
+
+Tracker references: [pm-8nzivt](../.agents/pm/features/pm-8nzivt.toon),
+[pm-pznhee](../.agents/pm/features/pm-pznhee.toon), and
+[pm-55yf1t](../.agents/pm/tasks/pm-55yf1t.toon).
+
+pm exposes optional workflow guidance and interactive context views without
+moving authority out of the public SDK or the tracker. Both extensions require
+explicit request-local negotiation. Clients that do not negotiate them retain
+the complete CLI, SDK, tool, prompt, and ordinary resource behavior.
+
+## Skills over MCP
+
+Skills support follows the current SEP-2640 draft at the exact revision
+`a3e147ca2710f68214247aecc729731ee1ae8d03`. Because the proposal is not a
+stable MCP extension, discovery advertises both `status: draft` and that exact
+revision. Every `skills/list`, `skills/get`, skill `resources/read`, and
+`resources/directory/read` request must independently declare:
+
+```json
+{
+  "extensions": {
+    "io.modelcontextprotocol/skills": {
+      "revision": "SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03",
+      "directoryRead": true
+    }
+  }
+}
+```
+
+`skills/list` is lexically ordered and cursor-paginated. Descriptors contain
+the parsed SKILL.md frontmatter, every file URI, byte size, SHA-256 digest,
+estimated token cost, package/MCP compatibility, origin, and an explicit
+`untrusted` trust marker. `skills/get` returns one descriptor without loading
+file bodies. Digests use the draft's `sha256:<hex>` representation.
+`resources/read` fetches one digest-bound file; the optional, cursor-paginated
+directory read returns one directory's direct child resource metadata only.
+Clients read selected file bodies through ordinary `resources/read` calls.
+
+The published package carries the four canonical pm skills. A repository may
+override a package skill by placing the same validated name below
+`.agents/skills`, and the returned origin changes to `workspace`. Overrides do
+not inherit trust: skill text is guidance, never implicit permission to execute
+commands or mutate the tracker.
+
+Security limits reject symbolic links, malformed or aliased YAML, mismatched
+directory/frontmatter names, stale cursors, oversized files, excessive file
+counts, and aggregate skill bodies above the declared bound. In accordance with
+the draft, pm accepts at most 512 resources and 16 MiB of total content per
+skill; the same 16 MiB ceiling applies to an individual resource. An origin is
+limited to 100 candidate skill directories and 32 MiB across all retained
+bodies. File counts and both byte budgets are reserved from filesystem metadata
+before a body is read, so an untrusted workspace cannot exceed the declared
+memory envelope before rejection. Each read is resolved from the immutable
+in-memory registry used to compute its digest.
+
+## MCP Apps
+
+pm implements the stable MCP Apps `2026-01-26` extension through the official
+`@modelcontextprotocol/ext-apps` metadata contracts. A client opts in with:
+
+```json
+{
+  "extensions": {
+    "io.modelcontextprotocol/ui": {
+      "specVersion": "2026-01-26",
+      "mimeTypes": ["text/html;profile=mcp-app"]
+    }
+  }
+}
+```
+
+Negotiated `tools/list` attaches `_meta.ui.resourceUri` to five existing,
+SDK-backed tools. `resources/list` and `resources/read` expose the corresponding
+`ui://` documents:
+
+| View | Authoritative tool | Purpose |
+| --- | --- | --- |
+| Context explorer | `pm_context` | Context, provenance, omissions, and token cost |
+| Relationship graph | `pm_graph` | Typed edges, explaining paths, and governance |
+| Plan and milestone | `pm_plan` | Steps, dependencies, decisions, and validation |
+| Assurance dashboard | `pm_validate` | Verdicts, evidence, and recovery paths |
+| Long-operation view | `pm_test` | Durable test and operation results |
+
+Every view is self-contained and requests no network, storage, camera,
+microphone, or location permission. It performs the MCP Apps initialization
+handshake, listens for tool input/result/cancellation and host-context events,
+bounds large renderings with an explicit truncation message, and retains the
+tool result's text fallback. Layout is responsive, keyboard focus is visible,
+and reduced-motion preferences are honored.
+
+Apps keep no durable project state and expose no hidden mutation path. The
+tracker, task store, mutation guards, consent, idempotency, and immutable
+receipts remain owned by existing SDK-backed MCP tools. A host that cannot or
+does not render Apps still receives meaningful tool text and structured data.
+Missing or incompatible optional Apps declarations therefore leave core tool
+and resource discovery undecorated; an explicit read of a `ui://` resource
+continues to fail closed unless the stable capability was negotiated.
+
+## Public SDK
+
+Use `PmMcpSkillRegistry`, `assertPmMcpSkillsCapability()`,
+`PM_MCP_SKILLS_SERVER_CAPABILITY`, `PM_MCP_APP_CONTRACTS`,
+`hasPmMcpAppsCapability()`, `decoratePmMcpToolsWithApps()`, and
+`renderPmMcpAppHtml()` from `@unbrained/pm-cli/sdk`. The server is a thin
+adapter over these contracts; custom hosts can project the same resources and
+security policy without importing pm server internals.

package/docs/QUICKSTART.md

@@ -9,7 +9,7 @@ Use this page to get from a clean repository to a tracked, verified item.
 - Claim before implementation.
 - Link changed files, docs, and tests to the item.
 - Close only after evidence is recorded.
-- Use `pm install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
+- Use `pm package install guide-shell --project` before `pm guide quickstart` or `pm guide workflows` when you need local docs routing.
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
@@ -23,10 +23,10 @@ pm --version
 For updates, use the registry package again:
 
 ```bash
-pm upgrade --cli-only
+pm package upgrade --cli-only
 ```
 
-`pm upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm.
+`pm package upgrade` uses `npm install -g @unbrained/pm-cli@latest` for the CLI/SDK and can also refresh installed pm packages. Do not use the GitHub git URL as the normal global update path. If a previous git-sourced install left a stale `pm` shim, run `pm package upgrade --cli-only --repair`, run `bash scripts/install.sh --repair` from a checkout, or uninstall the package before reinstalling from npm. The hidden `pm upgrade` alias remains compatible with existing automation and emits a migration hint on stderr.
 
 For one-off use:
 
@@ -39,8 +39,8 @@ Optional first-party packages are installable during init or on demand:
 ```bash
 pm init --defaults --with-packages
 pm package catalog --project
-pm install '*' --project
-pm install all --project
+pm package install '*' --project
+pm package install all --project
 pm package doctor --project --detail summary
 ```
 
@@ -78,16 +78,16 @@ pm create \
 
 Useful item types:
 
-| Type | Use |
-|------|-----|
-| `Epic` | broad outcome or initiative |
-| `Feature` | user-facing capability or major slice |
-| `Task` | implementation work |
-| `Chore` | maintenance, refactoring, or housekeeping work |
-| `Issue` | bug or defect |
-| `Decision` | recorded choice and rationale |
-| `Plan` | agent-optimized living plan with ordered steps and evidence |
-| `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning |
+| Type                                        | Use                                                         |
+| ------------------------------------------- | ----------------------------------------------------------- |
+| `Epic`                                      | broad outcome or initiative                                 |
+| `Feature`                                   | user-facing capability or major slice                       |
+| `Task`                                      | implementation work                                         |
+| `Chore`                                     | maintenance, refactoring, or housekeeping work              |
+| `Issue`                                     | bug or defect                                               |
+| `Decision`                                  | recorded choice and rationale                               |
+| `Plan`                                      | agent-optimized living plan with ordered steps and evidence |
+| `Event`, `Reminder`, `Milestone`, `Meeting` | calendar-aware planning                                     |
 
 ## Find and Claim Work
 

package/docs/README.md

@@ -44,6 +44,11 @@ pm guide release --json
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
 - [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.
+- [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.
+- [MCP Remote Transport, Authorization, and Migration](MCP_REMOTE_TRANSPORT_SECURITY.md) - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
 - [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.

package/docs/RELEASING.md

@@ -386,9 +386,18 @@ git push origin v<version>
   Bun caches plus an empty npm user config so maintainer credentials and cached
   metadata cannot mask a public-registry outage. The verifier dispatches a real
   `pm contracts` command through both explicit-bin and package-default
-  invocations, performs a JSON-RPC initialize handshake against the
-  symlink-resolved `pm-mcp` bin under both npx and bunx, derives bin coverage
-  from `package.json`, and proves missing-bin and missing-command controls fail.
+  invocations, performs stateless JSON-RPC `server/discover` against the
+  symlink-resolved `pm-mcp` bin under both npx and bunx, and launches the exact
+  public `pm-mcp-http` bin under both executors on an isolated loopback port for
+  a real Streamable HTTP `server/discover` exchange. Both transports require
+  canonical `2026-07-28` metadata/result envelopes. HTTP startup is bounded to
+  two 20-second attempts per executor so the complete retry budget remains below
+  the hosted step timeout. Signal-aware process-group cleanup escalates from
+  `SIGTERM` to `SIGKILL` after a bounded grace period, including when the outer
+  evaluator times out or an intermediate executor exits before its server
+  descendant. Direct executor exit is not treated as process-group cleanup. The
+  verifier derives bin coverage from `package.json`, and proves missing-bin and
+  missing-command controls fail.
 - exact-package installed acceptance through
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun
   install roots must contain the resolved executable, then each drives the

package/docs/SDK.md

@@ -62,6 +62,13 @@ Terminal recurrence and executable recovery are tracked by
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
+MCP hosts can build on the public stateless protocol, MRTR, cache/schema, and
+durable task primitives described in
+[MCP Interaction and Task SDK](SDK_MCP_INTERACTIONS.md). Those contracts are
+owned by [pm-rz9gep](../.agents/pm/features/pm-rz9gep.toon),
+[pm-rzs24j](../.agents/pm/features/pm-rzs24j.toon), and
+[pm-hv1x1x](../.agents/pm/features/pm-hv1x1x.toon).
+
 ## Install
 
 ```bash
@@ -244,6 +251,7 @@ Common authoring exports:
   the same remediation used by runtime activation.
 - `renderExtensionSurfaceMarkdown` (render a describe summary to a drift-free Markdown reference doc for a package README)
 - `checkExtensionManifestCompatibility` (author-time `pm_min_version`/`pm_max_version` check against a target pm version)
+- `inspectExtensionManifestSchema` / `lintExtensionManifestSchema` (pure raw-manifest schema inspection and actionable finding boundary)
 - `preflightExtension` (one-call capstone: lint + manifest synthesis + version-compat in a single consolidated report)
 - `RESERVED_ITEM_FIELD_NAMES` (the shared runtime/authoring denylist); `lintExtensionBlueprint`, preflight, and the test harness reject blueprint item fields that shadow these metadata keys before publication
 - `EXTENSION_CAPABILITIES`
@@ -2783,8 +2791,18 @@ bound, a `pm_min_version` the target is below, or a `block`-mode `pm_max_version
 the target exceeds) and stays quiet on advisory `*_unchecked` / `*_exceeded_warn`
 warnings, which still load:
 
+Use `lintExtensionManifestSchema(manifest)` when only the manifest vocabulary is
+in scope. It returns stable `manifest_unknown_key` and
+`no_version_bounds_declared` findings without requiring a target pm version.
+Compatibility results retain the existing combined `findings` array, while the
+dedicated lint result gives SDK, CLI, and MCP adapters a stable schema-only
+boundary.
+
 ```ts
-import { checkExtensionManifestCompatibility } from "@unbrained/pm-cli/sdk";
+import {
+  checkExtensionManifestCompatibility,
+  lintExtensionManifestSchema,
+} from "@unbrained/pm-cli/sdk";
 import { assertExtensionManifestCompatible } from "@unbrained/pm-cli/sdk/testing";
 
 // Inspect every bound outcome against a target version…
@@ -2793,6 +2811,9 @@ const report = checkExtensionManifestCompatibility(manifest, {
 });
 //   report.compatible === false, report.findings[0].code === "pm_min_version_unmet", …
 
+const schema = lintExtensionManifestSchema(manifest);
+//   schema.ok === false, schema.findings[0].path === "compatibility", …
+
 // …or fail the package's own suite when a bound would block the load.
 assertExtensionManifestCompatible(manifest, { pmVersion: "2026.6.23" });
 ```

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -152,22 +152,27 @@ invalid values.
 
 ## Cross an MCP boundary
 
-An embedding MCP client can add bounded `provenance` and `episode` fields to
-its initialize `clientInfo`. The server retains only those fields and applies
-them to later tool calls from that initialized client.
+An embedding MCP 2026-07-28 client can add bounded `provenance` and `episode`
+fields to request-local `io.modelcontextprotocol/clientInfo`. The server
+retains only those fields while processing that request; no later request
+inherits them.
 
 ```json
 {
-  "clientInfo": {
-    "name": "agent-host",
-    "version": "1.0.0",
-    "provenance": {
-      "role": "implementer",
-      "topic": "release readiness"
-    },
-    "episode": {
-      "id": "release-2026-08-01",
-      "label": "Release readiness"
+  "_meta": {
+    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+    "io.modelcontextprotocol/clientCapabilities": {},
+    "io.modelcontextprotocol/clientInfo": {
+      "name": "agent-host",
+      "version": "1.0.0",
+      "provenance": {
+        "role": "implementer",
+        "topic": "release readiness"
+      },
+      "episode": {
+        "id": "release-2026-08-01",
+        "label": "Release readiness"
+      }
     }
   }
 }

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -16,10 +16,16 @@ These contracts keep project management equal to context management: reads say w
 pm get pm-a1b2 --output-include id,title
 pm get pm-a1b2 --output-include item.id,item.title,linked
 pm get pm-a1b2 --output-include item,claim_state
+pm get pm-a1b2 --output-include comments,learnings,tests
 ```
 
 An unknown selector is a usage refusal that lists the valid vocabulary. Selecting the complete `item` object together with an item field is also refused because the two selectors express conflicting projection depths. Every successful projection carries an `omission_receipt` with the exact selectors needed to restore withheld item fields or sections.
 
+Collection selectors participate in the same pre-execution projection on CLI,
+SDK, and MCP transports. Requesting `comments`, `notes`, `learnings`, `files`,
+`tests`, `docs`, `reminders`, or `events` therefore loads only the named item
+collections before the universal output layer removes unrequested fields.
+
 Automatic receipts cover every heavy item collection (`comments`, `notes`,
 `learnings`, `files`, `tests`, `docs`, `reminders`, and `events`) plus `body`,
 `children`, `claim_state`, `linked`, and `schedule`. Empty included collections

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -1,6 +1,6 @@
 # SDK Evidence Traceability and Integrity
 
-Tracker references: [pm-f86lth](../.agents/pm/features/pm-f86lth.toon), [pm-cstuys](../.agents/pm/issues/pm-cstuys.toon), [pm-jb1ron](../.agents/pm/issues/pm-jb1ron.toon), [pm-2irc1p](../.agents/pm/issues/pm-2irc1p.toon), and [pm-u5c27w](../.agents/pm/issues/pm-u5c27w.toon).
+Tracker references: [pm-f86lth](../.agents/pm/features/pm-f86lth.toon), [pm-cstuys](../.agents/pm/issues/pm-cstuys.toon), [pm-jb1ron](../.agents/pm/issues/pm-jb1ron.toon), [pm-2irc1p](../.agents/pm/issues/pm-2irc1p.toon), [pm-u5c27w](../.agents/pm/issues/pm-u5c27w.toon), and [pm-blvfye](../.agents/pm/issues/pm-blvfye.toon).
 
 This contract turns linked evidence into a bidirectional context primitive. Items can continue to declare the files that explain their implementation, while agents and packages can resolve a source path back to its owning work without scanning tracker files at indexed scale.
 
@@ -127,3 +127,11 @@ such as `BD-30-A` and `BD-30-B` are distinct sibling work and receive only their
 ordinary title-token similarity; exact repetitions of the full code retain the
 strong `issue_code` signal. This keeps duplicate-close guidance from collapsing
 decomposed work that shares a numeric family prefix.
+
+Metadata validation applies a separate, evidence-backed title classifier.
+Upper-case prefixes remain conventional issue codes. Mixed-case prefixes must
+have a code delimiter, an explicit body marker/backtick reference, or match the
+configured item-id prefix. Natural-language compounds such as `Match-3`,
+`Covid-19`, and `Wi-Fi-6` therefore do not produce dishonest rename-or-merge
+warnings, while `GH-1118`, `Bug-12: ...`, and configured formats remain
+detectable without an ever-growing word dictionary.