@unbrained/pm-cli 2026.8.26 → 2026.8.28

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/OUTPUT_TOKEN_ACCOUNTING.md

@@ -1,6 +1,6 @@
 # Output Token Accounting
 
-Tracker references: [pm-t5dt4z](../.agents/pm/tasks/pm-t5dt4z.toon) and [pm-g3n00m](../.agents/pm/stories/pm-g3n00m.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), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 ## Agent Quick Context
 
@@ -39,20 +39,33 @@ The command still exits with its normal non-zero status; the receipt is additive
 
 ## Release-Level Task Entitlement
 
-[`agent-task-token-baseline.json`](agent-task-token-baseline.json) is the externally shipped release baseline. The gate executes the built CLI in an isolated workspace and covers:
+[`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:
 
-- a small-workspace read;
-- a scaled-workspace context read;
-- a returning-agent item read with a required-field completeness assertion;
-- a failing command with bounded recovery output.
+- bounded triage, scaled-workspace orientation, and returning-agent inspection;
+- a closed-domain refusal followed by the exact advertised shell-free retry;
+- an unknown option after valid flags followed by a corrected command;
+- create, inspect, close, and final-state confirmation through mutation receipts;
+- successful bulk partial-effect and no-effect exits without collapsing them into exit zero.
 
-Each invocation is independently byte-counted, its section sum is checked, and its consumed field is retained. A seeded million-token regression proves the ratchet fails. Run it with:
+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:
 
 ```bash
 pnpm quality:agent-task-token
 node scripts/release/agent-task-token-gate.mjs --negative-control
 ```
 
+Package authors can validate their own corpus with the same public contract before replay:
+
+```ts
+import { parsePmAgentTaskTranscriptCorpus } from "@unbrained/pm-cli/sdk/contracts";
+
+const corpus = parsePmAgentTaskTranscriptCorpus(JSON.parse(source));
+```
+
+The parser rejects unknown versions, empty tasks or steps, duplicate identities, output families that disagree with the command contract, refusal-only metadata on successful steps, terminal or otherwise unrecovered refusals, and recovery edges that do not point from a successful step to an earlier refusal.
+
 Refresh the committed ceiling only after an intentional reviewed output change:
 
 ```bash

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

@@ -47,6 +47,7 @@ pm guide release --json
 - [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.

package/docs/RELEASING.md

@@ -29,6 +29,8 @@ provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon), and
 authoritative blocker-recovery run selection by
 [pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
 same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
+Bounded Sentry request latency is tracked by
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon).
 
 ## Version Policy
 
@@ -210,6 +212,12 @@ events, and every `generic_failure` or `dependency_failed` remain blocking.
 This keeps rewording independent from release policy and makes stale or broad
 message allowlists impossible.
 
+Sentry API requests use a 120-second deadline by default. Operators can set
+`--sentry-request-timeout-ms` between `1` and `300000` when reproducing
+provider latency, while the emitted gate receipt records the effective value.
+The release workflow pins `120000`; query timeouts remain fail-closed and must
+not be treated as an empty issue set.
+
 If private reliability checks identify repeated user friction, either confirm the current release already contains the remediation with regression coverage or fix it before continuing.
 
 The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256 digests for every emitted bundle file. At startup, `pm` reports `bundle_integrity_torn_install` only when a module-loader failure is accompanied by manifest proof that an upgrade or rebuild changed, removed, or corrupted the active bundle. Reinstall `@unbrained/pm-cli` and retry after that diagnostic. Ordinary `ERR_MODULE_NOT_FOUND` and export failures with an intact manifest remain unexpected failures and must continue to block reliability gates.
@@ -358,7 +366,7 @@ git push origin v<version>
   tracked source path (apart from managed-extension install metadata).
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
-- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
+- reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; Sentry requests use the fail-closed bounded `--sentry-request-timeout-ms` contract (default `120000`, maximum `300000`); `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
 - optional Sentry release metadata and sourcemap upload when `SENTRY_AUTH_TOKEN` is configured
 - npm pack dry run and npx tarball smoke test
@@ -387,9 +395,17 @@ git push origin v<version>
   metadata cannot mask a public-registry outage. The verifier dispatches a real
   `pm contracts` command through both explicit-bin and package-default
   invocations, performs stateless JSON-RPC `server/discover` against the
-  symlink-resolved `pm-mcp` bin under both npx and bunx, requires canonical
-  `2026-07-28` metadata/result envelopes, derives bin coverage
-  from `package.json`, and proves missing-bin and missing-command controls fail.
+  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

@@ -1512,6 +1512,18 @@ edit/delete semantics, ownership guidance, history mutation metadata, and stable
 list pagination. MCP tool actions intentionally omit file input to prevent host
 filesystem access. Package authors can build custom annotation presentation
 layers without importing CLI modules.
+`CommentsCommandOptions.ifAbsent`, `NotesCommandOptions.ifAbsent`, and
+`LearningsCommandOptions.ifAbsent` give retrying agents one explicit idempotent
+annotation append contract. Equality is evaluated under the item writer lock
+after author resolution and text normalization, using the resolved author plus
+exact stored text. The first append returns `changed: true` and
+`mutation_receipt.changed_count: 1`; an exact retry returns the existing entry,
+`changed: false`, and `changed_count: 0` without changing the item, history, or
+derived search state. Different authors remain distinct, and the default
+without `ifAbsent` continues to append intentional duplicates. The option is
+valid only for append input and fails closed for list, edit, or delete modes.
+CLI `comments|notes|learnings --if-absent` and the corresponding MCP actions
+with `options.ifAbsent: true` are thin transports over this SDK behavior.
 `PmClient.notes` also accepts `addJson` for a validated structured context event. The persisted entry remains backward-readable through canonical `text` while exposing typed `format: "json"`, `data`, and `event_type` fields. `since`, `eventType`, `limit`, and `includeMeta` form the bounded query contract; the collection continues to use field-aware union merge semantics for concurrent branches.
 
 Customization convenience methods are the SDK baseline for project-specific pm

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -1,6 +1,6 @@
 # SDK Context Integrity
 
-Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
+Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon), and [pm-ea1yh2](../.agents/pm/issues/pm-ea1yh2.toon).
 
 Current closure tranche: [pm-fs8q9x](../.agents/pm/tasks/pm-fs8q9x.toon), [pm-gy885b](../.agents/pm/issues/pm-gy885b.toon), and [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
 
@@ -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
@@ -76,6 +82,17 @@ The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
 case, while the third names the nearest current-path spellings and explicitly
 terminates the otherwise-unbounded command search.
 
+## Retry-safe annotation mutations
+
+Comments, notes, and learnings expose one SDK-owned `ifAbsent` append contract.
+The item writer lock compares the resolved author and exact normalized stored
+text, so concurrent retries create one entry and one history event. The winning
+append reports `changed: true` and `mutation_receipt.changed_count: 1`; later
+exact retries return the existing entry with `changed: false` and
+`changed_count: 0`. Default appends remain duplicate-preserving. CLI
+`--if-absent` and MCP `ifAbsent` are thin transports, and `--full-history`
+remains the explicit escape hatch from bounded mutation receipts.
+
 ## Semantic flag and spelling contracts
 
 `listPmFlagLexicon()` classifies flags by meaning rather than spelling alone.

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.

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -61,6 +61,16 @@ published error vocabulary while still sharing classification, path redaction,
 and recovery guidance. Workspace snapshots use this compatibility path for
 their stable storage, resource, and permission fault codes.
 
+Package archives use one bounded validation and extraction boundary whether
+they come from a local path or `npm pack`. The SDK rejects links, escaping
+paths, unsupported entry types, oversized archives, and decompression growth
+before extraction. If npm reports an archive it did not create, callers receive
+the path-redacted `npm_package_archive_missing` refusal instead of a raw system
+`tar` exception; an archive reported outside the isolated pack destination is
+rejected as `npm_package_archive_unsafe`. This keeps package install behavior
+portable and prevents an untrusted registry artifact or package-manager result
+from bypassing the local-archive policy.
+
 ## CLI refusal ownership
 
 CLI adapters preserve SDK error codes, exit semantics, and actionable recovery

package/docs/TESTING.md

@@ -2,7 +2,7 @@
 
 This page describes safe local tests, linked tests, coverage, and release-readiness checks.
 
-Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), and [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon).
+Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon), [pm-mcxr](../.agents/pm/issues/pm-mcxr.toon), [pm-u42x](../.agents/pm/issues/pm-u42x.toon), [pm-atfm](../.agents/pm/features/pm-atfm.toon), [pm-xmp5](../.agents/pm/tasks/pm-xmp5.toon), [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), [pm-5cgm2z](../.agents/pm/chores/pm-5cgm2z.toon), [pm-avv3wx](../.agents/pm/issues/pm-avv3wx.toon), [pm-rizqb6](../.agents/pm/issues/pm-rizqb6.toon), [pm-95h7pg](../.agents/pm/issues/pm-95h7pg.toon), [pm-giks4s](../.agents/pm/issues/pm-giks4s.toon), [pm-xa3t0o](../.agents/pm/issues/pm-xa3t0o.toon), [pm-e97jyf](../.agents/pm/issues/pm-e97jyf.toon), [pm-efkvdy](../.agents/pm/issues/pm-efkvdy.toon), [pm-ed28wi](../.agents/pm/issues/pm-ed28wi.toon), and [pm-5ug5xq](../.agents/pm/issues/pm-5ug5xq.toon).
 
 ## Agent Quick Context
 
@@ -43,7 +43,11 @@ claims to the same canonical gate IDs. Hosted-only environment isolation and
 tracker-integrity steps remain explicit entries with reasons rather than
 silently disappearing from local parity.
 
-`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
+`node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, disables
+external Sentry delivery for the build, test workers, and their nested CLI
+children, then cleans the roots up. Instrumentation tests can still exercise
+Sentry initialization through their mocked module boundary; ordinary negative
+fixtures must never create production incidents from a developer host.
 
 Public SDK changes additionally run semantic surface and import-cost contracts:
 

package/docs/agent-task-token-baseline.json

@@ -1,25 +1,111 @@
 {
-  "version": 1,
+  "version": 3,
+  "transcript_version": 2,
+  "transcript_digest": "sha256:2bf91406426d2a9e5de1da10ba67f7b8e9d4a4baa09eb488fe89ae3925c78f3f",
   "estimator": "ceil(utf8_bytes / 4)",
   "measurement_scope": "output_before_token_accounting",
   "published_with_release": true,
-  "scenarios": [
+  "tasks": [
     {
-      "id": "small-workspace",
-      "max_estimated_tokens": 552
+      "id": "context-bootstrap",
+      "max_estimated_tokens": 1978,
+      "steps": [
+        {
+          "id": "triage",
+          "max_estimated_tokens": 552,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "orient",
+          "max_estimated_tokens": 1055,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect",
+          "max_estimated_tokens": 371,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "large-workspace",
-      "max_estimated_tokens": 1055
+      "id": "closed-domain-recovery",
+      "max_estimated_tokens": 630,
+      "steps": [
+        {
+          "id": "refuse-intent",
+          "max_estimated_tokens": 259,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "retry-intent",
+          "max_estimated_tokens": 371,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "returning-agent",
-      "max_estimated_tokens": 371
+      "id": "unknown-option-recovery",
+      "max_estimated_tokens": 585,
+      "steps": [
+        {
+          "id": "refuse-option",
+          "max_estimated_tokens": 422,
+          "accounting_mode": "independent_transport"
+        },
+        {
+          "id": "retry-option",
+          "max_estimated_tokens": 163,
+          "accounting_mode": "self_reported"
+        }
+      ]
     },
     {
-      "id": "failing-command",
-      "max_estimated_tokens": 219
+      "id": "lifecycle-mutation",
+      "max_estimated_tokens": 812,
+      "steps": [
+        {
+          "id": "create",
+          "max_estimated_tokens": 20,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-open",
+          "max_estimated_tokens": 363,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "close",
+          "max_estimated_tokens": 31,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "inspect-closed",
+          "max_estimated_tokens": 398,
+          "accounting_mode": "self_reported"
+        }
+      ]
+    },
+    {
+      "id": "bulk-effect-outcomes",
+      "max_estimated_tokens": 326,
+      "steps": [
+        {
+          "id": "create-bulk-target",
+          "max_estimated_tokens": 20,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "partial-effect",
+          "max_estimated_tokens": 174,
+          "accounting_mode": "self_reported"
+        },
+        {
+          "id": "no-effect",
+          "max_estimated_tokens": 132,
+          "accounting_mode": "self_reported"
+        }
+      ]
     }
   ],
-  "composite_max_estimated_tokens": 2197
+  "composite_max_estimated_tokens": 4331
 }