@unbrained/pm-cli 2026.8.7 → 2026.8.9

package/docs/MERGE_SAFETY.md

@@ -1,6 +1,6 @@
 # Multi-Branch Tracker Merge Safety
 
-Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
+Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity and concurrency fixes [pm-9q2t](../.agents/pm/issues/pm-9q2t.toon), [pm-cxyv](../.agents/pm/issues/pm-cxyv.toon), [pm-gpo7](../.agents/pm/issues/pm-gpo7.toon), [pm-m3nl](../.agents/pm/issues/pm-m3nl.toon), [pm-wwfd](../.agents/pm/issues/pm-wwfd.toon), and [pm-xdn6](../.agents/pm/issues/pm-xdn6.toon). Fresh-init fence ownership is tracked by [pm-1w3ljt](../.agents/pm/issues/pm-1w3ljt.toon); runtime-cache index governance by [pm-hous](../.agents/pm/issues/pm-hous.toon); local allocation safety by [pm-khdq](../.agents/pm/issues/pm-khdq.toon); fence-coverage completeness and drift detection by [pm-i4fx](../.agents/pm/issues/pm-i4fx.toon); package-defined item coverage by [pm-5rexki](../.agents/pm/issues/pm-5rexki.toon); non-item JSON coverage by [pm-gjicmx](../.agents/pm/issues/pm-gjicmx.toon); portable driver identity by [pm-w91mvg](../.agents/pm/issues/pm-w91mvg.toon); pending receipt validation by [pm-ysqb6n](../.agents/pm/issues/pm-ysqb6n.toon); receipt classification by [pm-jtwsct](../.agents/pm/issues/pm-jtwsct.toon); direction-independent item conflict selection by [pm-dlx7v7](../.agents/pm/issues/pm-dlx7v7.toon); corrected reconciliation guidance by [pm-lwmstb](../.agents/pm/issues/pm-lwmstb.toon); cross-branch id collision safety by [pm-pibw](../.agents/pm/issues/pm-pibw.toon); auditable merge history by [pm-9j2r3b](../.agents/pm/tasks/pm-9j2r3b.toon); durable conflict decisions by [pm-rh98vo](../.agents/pm/issues/pm-rh98vo.toon); continuous conformance by [pm-76dnfg](../.agents/pm/tasks/pm-76dnfg.toon); workspace-wide CI enforcement by [pm-pdr8t1](../.agents/pm/tasks/pm-pdr8t1.toon); post-merge reconciliation by [pm-mfkv92](../.agents/pm/issues/pm-mfkv92.toon); this repository's own adoption by [pm-iwsj](../.agents/pm/chores/pm-iwsj.toon).
 
 pm stores project context as reviewable repository files. Concurrent agents can therefore use ordinary branches and worktrees, but tracker artifacts need semantic merge behavior: raw line merging cannot preserve TOON collection counts, JSON object structure, or append-only history hash chains.
 
@@ -56,12 +56,12 @@ pm merge install --dry-run --json
 
 | Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                          |
 | ---------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; format-specific drivers avoid passing the repository path through Git's shell command, append-like collections use set union, `updated_at` uses latest timestamp, and canonical serialization recomputes TOON counts.            |
+| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses latest timestamp, scalar conflicts select a stable direction-independent value, and canonical serialization recomputes TOON counts.                                     |
 | `history/*.jsonl`                                                | `pm-history`                        | Preserves the common prefix and both divergent suffixes, orders deterministically, then re-anchors the resulting hash chain.                                                                                                                            |
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
-When both sides change the same scalar or JSON leaf differently, the driver writes a parseable preferred-side result but exits nonzero. Git keeps the path conflicted so a human or coordinating agent must review the losing value and explicitly `git add` the resolution. Use `--prefer theirs` only when that is the intended resolution policy.
+When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution.
 
 The driver result's `guidance` always points unresolved conflicts to `pm merge report`. When a clone-local receipt exists, guidance includes its privacy-safe receipt and item ids for exact correlation; discarded values remain confined to the local receipt and never appear in generic logs or tracker history. Tracked by [pm-fbrz7p](../.agents/pm/issues/pm-fbrz7p.toon).
 
@@ -97,9 +97,16 @@ After every branch merge that touches `.agents/pm`, run:
 ```bash
 pm merge reconcile --dry-run --json
 pm merge reconcile --message "Reconcile merged tracker histories" --json
+# Required only after every discarded field has been reviewed or re-applied:
+pm merge reconcile --force --message "Accept reviewed merge decisions" --json
 ```
 
 The preview reports every drifted stream and pending receipt without mutation.
+Lossless receipts are reported as provenance but do not become blocking merge
+decisions. Receipts with discarded scalar values remain blocking and the apply
+pass refuses them unless the coordinator explicitly supplies `--force` after
+review. This prevents a routine history repair from silently accepting data
+loss while preserving a zero-noise path for merges that retained both changes.
 It exits nonzero while either merge-critical validation check is non-green, so
 CI and explicit post-merge hooks cannot approve unresolved receipts or drift.
 The apply pass uses the audited history rewrite boundary to append a

package/docs/README.md

@@ -56,6 +56,7 @@ pm guide release --json
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [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 Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
+- [SDK Context Integrity](SDK_CONTEXT_INTEGRITY.md) - truthful `get` projections, bounded annotation mutations, shared author coordinates, health provider boundaries, and changeset-aware replication gates.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [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.

package/docs/RELATIONSHIP_GRAPH.md

@@ -16,7 +16,7 @@ Ordering-cycle validation considers only kinds whose registry definition sets `o
 
 SDK queries are deterministic, bounded, cancellation-aware, and return explicit visited-node, inspected-edge, truncation, and continuation metadata. The graph kernel supplies adjacency, incoming and outgoing traversal, closure, shortest path, reverse impact through incoming traversal, and induced subgraphs. The in-memory index is rebuildable directly from item metadata; durable large-workspace indexes remain an interchangeable storage implementation.
 
-Ordering kinds also declare precedence. `source_before_target` means the source must execute first; `target_before_source` models dependency-shaped edges such as `blocked_by`. Custom kinds default to source-first for compatibility, but domain packages should declare the direction explicitly. Analytics consume this field and never infer execution meaning from the label.
+Ordering kinds also declare precedence. `source_before_target` means the source must execute first; `target_before_source` models dependency-shaped edges such as `blocked_by`. Custom kinds default to source-first for compatibility, but domain packages should declare the direction explicitly. Analytics consume this field and never infer execution meaning from the label. Built-in canonical spellings, compatibility aliases, and inverse actionability are defined in [Dependency-kind contract](DEPENDENCY_KIND_CONTRACT.md).
 
 Hierarchy kinds likewise declare which endpoint is the structural parent. `source_parent` supports domain edges such as company `owns` asset, while `target_parent` preserves item-shaped child `parent` parent storage. Custom hierarchy kinds default to `source_parent`; packages should declare the orientation explicitly when their persisted edge shape differs. Context explanations use this contract instead of inferring ancestry from a kind name.
 

package/docs/RELEASING.md

@@ -21,7 +21,10 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), stable peer compatibility
 [pm-csuce0](../.agents/pm/issues/pm-csuce0.toon), and artifact budgets
 [pm-998juj](../.agents/pm/tasks/pm-998juj.toon), plus exact-tag recovery
-[pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon).
+[pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon), and SDK-bound reliability
+classification [pm-dqtzva](../.agents/pm/issues/pm-dqtzva.toon).
+The local/hosted gate selection contract is tracked by
+[pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
 
 ## Version Policy
 
@@ -177,6 +180,16 @@ Run the public Sentry/telemetry threshold gate through the package script alias:
 pnpm sentry:telemetry:gate -- --telemetry-mode best-effort
 ```
 
+The Sentry threshold gate reads the latest event for each issue and classifies
+expected handled failures from the SDK error catalog. An event is ignored only
+when it is handled, its `pm.error_code` resolves to a declared canonical code,
+its `pm.exit_code` exactly matches that code's transport contract, and the
+semantic class is `usage`, `not_found`, or `conflict`. Message and title prose
+never participate. Unknown codes, missing or mismatched exits, unhandled
+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.
+
 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.
@@ -184,7 +197,19 @@ The build writes `dist/cli-bundle/bundle-manifest.json` atomically with SHA-256
 4. Run the same release pipeline locally.
 
 Push the final implementation commit first, wait for DeepScan and CodeFactor to
-finish on that reviewed SHA, and run the mandatory local hosted-analysis proof:
+finish on that reviewed SHA, then run the canonical registry-owned preflight:
+
+```bash
+pnpm verify:preflight
+```
+
+The registry supplies the ordered executable plan, command arguments,
+environment, capture policy, and explicit skip policy. Its receipt distinguishes
+passed checks from declared skips. The same registry maps named PR, nightly,
+and release workflow gates; hosted-only entries must explain why no faithful
+local equivalent exists.
+
+The preflight includes the mandatory local hosted-analysis proof:
 
 ```bash
 pnpm quality:hosted-analysis

package/docs/SCRIPTING.md

@@ -1,6 +1,6 @@
 # CLI Scripting Contract
 
-Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
+Tracked by [pm-psy1](../.agents/pm/tasks/pm-psy1.toon), [pm-hqa8g1](../.agents/pm/tasks/pm-hqa8g1.toon), [pm-gknu](../.agents/pm/issues/pm-gknu.toon), [pm-999jh7](../.agents/pm/issues/pm-999jh7.toon), and [pm-srns](../.agents/pm/issues/pm-srns.toon).
 
 Use this contract when composing `pm` with shells, CI runners, `jq`, or another process. Exact flags remain discoverable from `pm <command> --help --json` and `pm contracts --command <command> --flags-only --json`.
 
@@ -14,6 +14,32 @@ Use this contract when composing `pm` with shells, CI runners, `jq`, or another
 | `3`  | Requested tracker or resource was not found.                                     | Correct the path or ID.                              |
 | `4`  | State or concurrency conflict.                                                   | Refresh live state before deciding whether to retry. |
 | `5`  | A required dependency operation failed.                                          | Inspect the dependency evidence before retrying.     |
+| `6`  | The request succeeded but matched nothing to change.                              | Treat as success and inspect the effect receipt.      |
+| `7`  | The request succeeded and changed only part of the selected targets.              | Treat as success and inspect unmatched/skipped rows.  |
+
+Exits `0`, `6`, and `7` are successful outcomes. Bulk mutation envelopes repeat
+the distinction as `outcome: effect`, `outcome: no_effect`, or `outcome:
+partial_effect` with the same `exit_code`. Because POSIX shells treat every
+nonzero exit as a false condition, scripts invoking effect-aware bulk commands
+must preserve and classify the status explicitly rather than relying on a bare
+`if` condition:
+
+```bash
+set +e
+result=$(pm update-many --ids "$ids" --tags reviewed --json)
+status=$?
+set -e
+
+case "$status" in
+  0|6|7) printf '%s\n' "$result" | jq '{outcome, matched_count, updated_count}' ;;
+  *)     printf '%s\n' "pm update-many failed with exit $status" >&2; exit "$status" ;;
+esac
+```
+
+The generated contract is authoritative. `pm contracts --command update-many
+--full --json` returns `command_exit_contracts.vocabulary` and the selected
+command's exhaustive `exit_codes`; SDK consumers can use the same declarations
+and `isPmSuccessfulExitCode` from `@unbrained/pm-cli/sdk/contracts`.
 
 Successful structured results are written to stdout. Diagnostics, warnings, profiles, and errors are written to stderr so `--json`, `--format ndjson`, CSV, and table stdout remain pipe-safe. Never merge stderr into stdout before parsing structured output.
 

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -2,7 +2,10 @@
 
 Tracker references: [pm-9wbiye](../.agents/pm/issues/pm-9wbiye.toon),
 [pm-rbg1qo](../.agents/pm/issues/pm-rbg1qo.toon), and
-[pm-oqo9l2](../.agents/pm/features/pm-oqo9l2.toon).
+[pm-oqo9l2](../.agents/pm/features/pm-oqo9l2.toon),
+[pm-3zgh2c](../.agents/pm/features/pm-3zgh2c.toon),
+[pm-eq9dlw](../.agents/pm/issues/pm-eq9dlw.toon), and
+[pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
 
 Project management is context management. The public SDK therefore carries a
 session's purpose and episode boundary through the same immutable history that
@@ -59,7 +62,7 @@ import { spawn } from "node:child_process";
 import { agentSessionEnvironment } from "@unbrained/pm-cli/sdk";
 
 const session = {
-  provenance: { role: "grader", topic: "package acceptance" },
+  provenance: { role: "release-operator", topic: "package acceptance" },
   episode: { id: "package-acceptance", label: "Package acceptance" },
 };
 
@@ -75,6 +78,36 @@ The environment contract is `PM_AGENT_SESSION_ROLE`,
 context keys, distinct from intentional per-observation overrides such as
 `PM_AGENT_MODEL`.
 
+Roles use the controlled values `implementer`, `implementation`,
+`investigator`, `orchestrator`, `planner`, `release-operator`, and `reviewer`.
+Case, spaces, and underscores normalize to lowercase hyphenated values. Other
+values are ignored instead of polluting analytics. Presence-only harness flags,
+including `CLAUDE_CODE_CHILD_SESSION=1`, are detection evidence and are never
+persisted as semantic roles.
+
+For ordinary CLI mutations, the detector can infer an `implementer` or
+`reviewer` role from the bounded command verb and a topic from an explicit
+`pm-...` item argument. Explicit overrides, session declarations, and trusted
+host declarations retain precedence over this inference.
+
+## Diagnose missing provenance
+
+`diagnoseAgentIdentity()` is the additive diagnostic companion to
+`detectAgentIdentity()`. It returns the same privacy-safe identity plus a
+`provenance_outcomes` row for every built-in dimension. Each row is
+`resolved`, `unavailable`, or `failed`, carries rule version `v1`, and may name
+the bounded built-in resolver. It never contains environment values, session
+paths, prompts, or file contents.
+
+New mutation history records failed resolver outcomes under
+`context.agent_provenance_outcomes`; ordinary unavailable dimensions retain
+the compact legacy-compatible null projection. A resolver is only counted as
+attempted when its required input exists. Consequently `pm health` can report
+`provenance_resolver_zero_success:<harness>:<dimension>:<resolver>:<attempts>`
+without confusing an unavailable harness signal with a failed resolver. The
+warning is advisory and the storage check includes the bounded attempt and
+success counters for diagnosis.
+
 ## Cross an MCP boundary
 
 An embedding MCP client can add bounded `provenance` and `episode` fields to

package/docs/SDK_CONTEXT_INTEGRITY.md

@@ -0,0 +1,81 @@
+# 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), and [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon).
+
+## Agent Quick Context
+
+These contracts keep project management equal to context management: reads say what they omit, writes return only newly useful context, diagnostics do not unexpectedly call remote providers, and every transport delegates domain validation to the same SDK primitive. Package authors can use the same primitives without reproducing CLI parsing rules.
+
+## `get` output selectors
+
+`pm get` has one declared selector namespace. Top-level sections use their names, while item fields may be written as either a bare field or `item.<field>`:
+
+```bash
+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
+```
+
+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.
+
+Standard and brief item reads expose the stable `collection_counts` selector;
+full reads retain those counts and normalize every supported collection key to
+an array. `--output-include item.collection_counts` therefore uses the same
+selector grammar and omission receipts as any other SDK-owned item field.
+
+The same SDK-owned read-output registry now declares `package manage` as a first-class read surface. Package authors can resolve either `package manage` or `package-manage` to its canonical contract and discover the universal include, amount, cost, and encoding dimensions without copying CLI knowledge.
+
+## Bounded annotation mutations
+
+Adding, editing, or deleting a comment, note, or learning returns the changed entry plus mutation and omission receipts. The reply size therefore stays independent of the item’s existing annotation history. Pass `--full-history` when a human or integration genuinely needs the complete post-mutation collection:
+
+```bash
+pm comments pm-a1b2 "Decision evidence"
+pm comments pm-a1b2 --edit 3 --message "Corrected evidence" --full-history
+pm notes pm-a1b2 --delete 2 --full-history
+```
+
+SDK callers use `fullHistory: true`; MCP callers use `full: true`. The default stays bounded on every transport. An omission receipt identifies the semantic `full_history` selector and includes its CLI (`--full-history`), SDK (`fullHistory`), and MCP (`full`) spellings, so non-CLI consumers never need to interpret shell-only guidance.
+
+## Author acknowledgment coordinates
+
+CLI, SDK, and MCP use the same selector and coordinate parser for `history-author-acknowledge`. A coordinate is `<item-id>:<line>` or `_workspace:<line>`, with a positive one-based line number. Exactly one of explicit events or `all_actionable` is required.
+
+```bash
+pm history-author-acknowledge \
+  --event _workspace:4 \
+  --attributed-author import-agent \
+  --reviewer maintainer \
+  --reason "Verified workspace provenance"
+```
+
+The SDK exposes `resolveUnknownAuthorAcknowledgmentSelector` and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar.
+
+## Health provider boundary
+
+`pm health` is read-only by default and never refreshes embeddings merely because a semantic provider is configured. Provider I/O requires `--refresh-vectors`; `--skip-vectors` or `--no-refresh` records the explicit non-provider path. Provider requests remain bounded by the configured embedding timeout, and a failed refresh reports the responsible vector diagnostic plus the skip remediation.
+
+Storage integrity is evaluated independently of that provider boundary. Lossless merge receipts remain visible as provenance, while only receipts containing discarded scalar values produce `merge_decisions_unreviewed` guidance; neither classification enables vector refresh or remote provider I/O.
+
+The storage check also reads at most 10,000 local immutable events for bounded
+agent-provenance resolver outcomes. This scan performs no network or provider
+I/O, tolerates malformed streams already owned by integrity diagnostics, and
+reports an advisory warning only when a resolver was actually attempted but
+never succeeded.
+
+## Replication and refusal gate
+
+`scripts/release/surface-replication-sets.json` declares replicated SDK, CLI, MCP, documentation, and test members. `pnpm quality:surface-replication` activates sets from the Git changeset, verifies every member invariant, and reports:
+
+- active set recurrence density;
+- the largest source member’s utilization of the mandatory file-size cap;
+- every remaining CLI-owned `PmCliError`, grouped by an explicit adapter-level disposition;
+- applied waivers, including their PM owner and expiry.
+
+Query waivers directly with:
+
+```bash
+node scripts/release/surface-replication-gate.mjs --list-waivers
+```
+
+Waivers are never implicit: they require a canonical PM item, a reason, an exact set member, and an expiry date. New or moved CLI refusals fail until the inventory is updated or the rule is delegated into the SDK. The same declaration runs locally and inside the required static-quality workflow.

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -0,0 +1,58 @@
+# SDK Runtime Boundaries
+
+Tracker: [pm-1eted6](../.agents/pm/issues/pm-1eted6.toon),
+[pm-3lhth4](../.agents/pm/issues/pm-3lhth4.toon), and
+[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon).
+
+These SDK primitives keep host and project-runtime policy consistent across the
+bundled CLI, packages, and automation without requiring consumers to reproduce
+private CLI parsing rules.
+
+## Project runtime compatibility
+
+Packages and automation can call `inspectProjectRuntimeCompatibility` before a
+mutation, or `assertProjectRuntimeCompatibility` when refusal semantics are
+preferred. The SDK discovers the strongest project-local pm version pin from
+the package manifest, installed package metadata, and supported lockfiles. A
+CLI older than that pin refuses mutation with
+`project_runtime_stale_mutation`; read commands stay available so an agent can
+recover context before upgrading. Stale reads, including `context` and
+read-only `health` invocations, emit the non-blocking
+`project_runtime_stale_read` warning. JSON modes write a single structured
+warning object to stderr, leaving the command's normal stdout envelope valid;
+human modes identify both versions, the redaction-safe pin source, and a
+package-manager-neutral recovery action. SDK callers receive the same warning
+inside `ProjectRuntimeCompatibilityResult`. `PM_ALLOW_STALE_CLI=1` is the
+explicit, auditable emergency override.
+
+The public `isProjectMutatingInvocation` classifier applies the same decision
+to package hosts and the bundled CLI. It resolves mixed command families by
+their effective action: configuration, merge, schema, profile, package,
+telemetry, workspace snapshot, template, VCS, validation, health, test, linked
+artifact, and changelog reads remain available while their write forms are
+fenced. Help, checks, previews, and dry runs remain reads, so compatibility
+enforcement does not turn diagnostics into writes.
+
+## Host-environment fault boundary
+
+Use `withHostEnvironmentBoundary` around filesystem and resource operations
+that cross into the host. It translates recognized Node errno failures into
+the stable, path-redacted `host_environment_capacity_fault`,
+`host_environment_permission_fault`, or `host_environment_resource_fault`
+contracts. `classifyHostEnvironmentFault` supports diagnostics that need a
+non-throwing classification, while `translateHostEnvironmentFault` supports an
+existing catch boundary. Non-errno failures are returned unchanged and must
+not be relabeled as environment faults.
+
+Existing SDK surfaces can supply category-specific `codes` to preserve their
+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.
+
+## CLI refusal ownership
+
+CLI adapters preserve SDK error codes, exit semantics, and actionable recovery
+guidance when presenting refusals as human-readable or structured output.
+Host-only validation remains at the transport boundary, while rules shared by
+packages and commands live in public SDK primitives so callers receive the
+same refusal contract regardless of entrypoint.

package/docs/SELF_DESCRIBING_CONTEXT_CONTRACTS.md

@@ -79,6 +79,7 @@ The default summary stays bounded. Larger intent and error catalogs are emitted
 - recovery guidance;
 - source modules that emit the code.
 - inferred CLI command roots (`*` for cross-cutting runtime failures).
+- canonical code and compatibility aliases for concept-level handling.
 
 Existing catalog entries are recorded in `scripts/error-code-stability.json`.
 The generator refuses to remove one of those stable codes unless the reviewed
@@ -86,6 +87,18 @@ compatibility ledger is changed explicitly. Newly discovered codes are emitted
 as provisional until deliberately promoted, so adding a runtime declaration
 does not accidentally promise permanent compatibility.
 
+The compatibility ledger also pins every stable code to its reviewed process
+exit. An executable `PmCliError` declaration that disagrees with that mapping
+fails generation, and a stable code without a mapping fails the drift check.
+Reviewed alias groups preserve every emitted legacy spelling while exposing one
+canonical concept to SDK, package, CLI-contract, and observability consumers.
+Aliases must resolve directly to a declared stable canonical code and share its
+exit class; cycles, missing targets, and transport mismatches fail closed.
+
+Use `resolvePmErrorCodeContract` when the exact emitted spelling matters, and
+`resolveCanonicalPmErrorCodeContract` when one handler should cover a complete
+compatibility group.
+
 `PM_ERROR_CODE_EXIT_CLASS_CONTRACTS` is the portable shell taxonomy: exit 1 is
 generic failure, 2 is usage, 3 is not-found, 4 is conflict, and 5 is dependency
 failure. Catalog validation rejects a code whose declared semantic class and

package/docs/SENTRY_CONTRACT_EPOCHS.md

@@ -0,0 +1,20 @@
+# Sentry Error Contract Epochs
+
+Tracker reference: [pm-h75tjh](../.agents/pm/issues/pm-h75tjh.toon).
+
+The release reliability gate declares `2026.8.7` as the minimum producer
+version for canonical `pm.error_code` and `pm.exit_code` tags. An unresolved
+event with a known older release is reported as `legacy_pre_contract`; it does
+not block a current release merely because it cannot satisfy a future
+producer contract.
+
+Events from the minimum producer or newer remain blocking when they are
+unexpected faults or lack the required tags. Events with no parseable producer
+version are also blocking. JSON output includes the minimum version,
+`legacy_pre_contract_total`, bounded legacy ids, and a bounded blocking-reason
+row for each current issue. Expected handled usage, not-found, and conflict
+errors remain a separate non-blocking class.
+
+This epoch rule only changes gate classification. It does not resolve, delete,
+or hide Sentry issues, and it does not weaken fatal or error thresholds for
+current producers.

package/docs/TESTING.md

@@ -16,6 +16,8 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
 
 Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
+Local/hosted gate parity is tracked by [pm-ei6x66](../.agents/pm/tasks/pm-ei6x66.toon).
+
 ## Standard Local Checks
 
 ```bash
@@ -26,6 +28,21 @@ node scripts/run-tests.mjs test
 node scripts/run-tests.mjs coverage
 ```
 
+For the exact ordered local preflight used to make release-readiness claims,
+run the registry-owned entrypoint:
+
+```bash
+pnpm verify:preflight
+```
+
+`scripts/release/gate-registry.json` is the executable plan for this command:
+each ordered step declares its command, arguments, environment, capture mode,
+and whether an explicit skip flag is permitted. Receipts distinguish passed
+steps from declared skips, and `quality:gate-registry` maps hosted workflow
+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.
 
 Public SDK changes additionally run semantic surface and import-cost contracts:

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

@@ -14,12 +14,12 @@
     },
     {
       "id": "returning-agent",
-      "max_estimated_tokens": 336
+      "max_estimated_tokens": 383
     },
     {
       "id": "failing-command",
       "max_estimated_tokens": 197
     }
   ],
-  "composite_max_estimated_tokens": 2390
+  "composite_max_estimated_tokens": 2437
 }

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.7"
+    "version": "2026.8.9"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.7",
+      "version": "2026.8.9",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -132,6 +132,7 @@
     "quality:gate-registry": "pnpm build && node scripts/release/gate-registry.mjs",
     "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
+    "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
     "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
@@ -163,6 +164,7 @@
     "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
+    "verify:preflight": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "release:pipeline": "node scripts/release/run-release-pipeline.mjs",
     "release:pipeline:dry-run": "node scripts/release/run-release-pipeline.mjs --dry-run",
     "release:verify-published": "node scripts/release/verify-published-release.mjs",
@@ -218,7 +220,7 @@
     "fast-check": "^4.9.0",
     "greptile": "^3.3.1",
     "jscpd": "^5.0.14",
-    "tsx": "^4.23.8",
+    "tsx": "^4.23.11",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

package/packages/pm-governance-audit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

package/packages/pm-guide-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

package/packages/pm-lifecycle-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

package/packages/pm-linked-test-adapters/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

package/packages/pm-search-advanced/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.7",
+  "version": "2026.8.9",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",