@unbrained/pm-cli 2026.9.3 → 2026.9.5

package/docs/MERGE_SAFETY.md

@@ -5,7 +5,19 @@ Tracked by [pm-wc1r](../.agents/pm/features/pm-wc1r.toon), with the integrity an
 Lossless receipt health gating is tracked by
 [pm-baksix](../.agents/pm/issues/pm-baksix.toon), and executable remediation
 that performs settlement is tracked by
-[pm-r0p3at](../.agents/pm/issues/pm-r0p3at.toon).
+[pm-r0p3at](../.agents/pm/issues/pm-r0p3at.toon). Immutable record sealing and
+retained re-anchor evidence are tracked by
+[pm-javbsq](../.agents/pm/issues/pm-javbsq.toon) and
+[pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon); preferred-era receipt-summary
+compatibility is tracked by
+[pm-wn3ee5](../.agents/pm/issues/pm-wn3ee5.toon).
+Lossless concurrent acceptance-criteria composition is tracked by
+[pm-inn5y5](../.agents/pm/issues/pm-inn5y5.toon).
+Recency-aware scalar convergence, bounded fresh-clone decision evidence, and
+audited pre-durable receipt dispositions are tracked by
+[pm-7wzb6d](../.agents/pm/issues/pm-7wzb6d.toon),
+[pm-mg13iz](../.agents/pm/issues/pm-mg13iz.toon), and
+[pm-cf4t42](../.agents/pm/issues/pm-cf4t42.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.
 
@@ -59,12 +71,12 @@ pm merge install --dry-run --json
 
 ## Artifact semantics
 
-| Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                          |
-| ---------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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.                   |
+| Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses the latest timestamp, scalar conflicts select the value from the later document update with stable value order as an equal-timestamp tie-break, 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.                                               |
 
 The `tests` collection has an additional execution-safety rule. Its semantic
 identity excludes provenance so the same command/context does not duplicate
@@ -80,17 +92,50 @@ boundary for append-like data that becomes executable after a merge; ordinary
 notes, files, and other non-executable collections retain normal set-union
 behavior.
 
-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. Item results and receipts expose the caller's `requested_preference`; the per-decision `retained` and `discarded` values or hashes are authoritative because stable value order can retain either side. Readers normalize the legacy receipt key `preferred`, while new receipts no longer emit it. 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. This correction is tracked by [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon).
+Although `acceptance_criteria` is serialized as a semicolon-delimited scalar
+for backward compatibility, the item driver treats its parsed criteria as a
+collection. Independent additions compose in branch order, removals made by
+either side remain removed, the field is reported in `union_fields`, and a
+lossless merge does not create a scalar conflict decision. This gives repeated
+`pm update --add-ac` mutations the same multi-branch preservation guarantee as
+native append-like metadata without a storage migration.
+
+When both sides change the same item scalar differently, the driver retains the
+value from the document with the later `metadata.updated_at` timestamp. Equal
+timestamps fall back to stable value ordering, so reversing Git's ours/theirs
+labels still converges to the same result. Item results, driver results, and
+receipts expose `conflict_resolution: latest_document_update` and
+`requested_preference_applied: false`; each conflict decision adds
+`retained_side` and `resolution_basis` so review automation can distinguish a
+recency decision from the stable tie-break. The caller's
+`requested_preference` remains observable but does not override item scalar
+convergence. Readers continue to accept legacy `preferred_side` and
+`stable_value_order` receipts and normalize the legacy `preferred` key. JSON
+leaf conflicts retain their explicit preferred-side policy. Git keeps the item
+path conflicted so a human or coordinating agent must review the discarded
+value and explicitly `git add` the resolution.
+
+The exact object `{ "pm_item_scalar_missing": true }` is reserved for
+JSON-stable missing-value evidence. Item merge inputs reject that object as a
+present metadata value, while the hashing primitive independently separates
+present and missing domains. This prevents extension data from impersonating a
+deletion without wrapping every ordinary scalar in receipt output.
 
 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).
 
 For item conflicts, the driver writes a clone-local receipt below the Git
 directory and a durable privacy-safe sidecar below `merge-receipts/` in the
 tracker. The local receipt contains retained and discarded values so recovery
-does not depend on a reflog. The tracked sidecar contains only field names and
-value hashes, so fresh clones and CI can still fail closed on an unreviewed
-decision without publishing either value. When both copies exist the SDK
-deduplicates them and prefers the locally recoverable copy:
+does not depend on a reflog. The tracked sidecar applies the versioned
+`bounded_non_sensitive_scalars_v1` policy. Built-in lifecycle statuses,
+priority integers from 0 through 4, bounded risk/confidence/severity ordinals,
+and `null` are stored with both their value and matching hash. All other values
+remain hash-only. `value_availability` distinguishes `bounded_inline`, `mixed`,
+and `hash_only`, while the clone-local receipt remains `clone_local`. This lets
+a fresh-clone reviewer recover ordinary control-plane decisions without
+publishing titles, descriptions, custom statuses, or other potentially private
+content. When both copies exist the SDK deduplicates them and prefers the
+locally recoverable copy:
 
 ```bash
 pm merge report
@@ -108,7 +153,9 @@ that distinction without returning malformed contents.
 loss-aware contract through `complete`, `invalid_evidence_count`, bounded
 `invalid_evidence[]`, `invalid_evidence_truncated`, and
 `clone_local_evidence_resolved`. Each rejected candidate reports a stable
-reason plus its `clone_local`, `durable`, or copy-consistency source. A safe
+reason plus its `clone_local`, `durable`, or copy-consistency source. Schema and
+identity failures additionally expose a bounded `validation_error` such as
+`required_fields`, `item_path`, `filename`, or `durable_decisions`. A safe
 receipt filename is returned as `receipt_id`; unsafe candidate names are
 represented only by `candidate_name_hash`, and malformed contents are never
 returned. The detail list is capped at 100 rows while the count remains exact,
@@ -118,13 +165,26 @@ POSIX instead of treating platform-specific `ENOENT`/`ENOTDIR` spellings as
 equivalent. Full health also cross-checks the privacy-safe receipt summaries in
 append-only history against valid pending and reconciled evidence. Missing
 evidence emits `merge_receipt_history_reference_missing:<n>` with bounded item,
-history-line, and receipt-id-or-hash coordinates. Its remediation enumerates
-the exact references and directs recovery from an authoritative clone or
-backup; it never recommends deleting receipts or rewriting history. The CLI
+history-line, and receipt-id-or-hash coordinates. Recover an available receipt
+from an authoritative clone or backup first. For an exact reference whose
+history-event timestamp predates tracked durable receipts, `pm merge reconcile
+--force` can append a `merge_reconcile` audit event containing the original
+item, line, receipt id, timestamp, and the closed
+`legacy_clone_local_only` reason. Health accepts only that exact coordinate and
+reports it through `accepted_missing_merge_receipt_dispositions`; it never
+rewrites or deletes the original history. The audit event must also occur after
+the referenced history line; an earlier event cannot pre-authorize a later
+missing receipt. Missing post-durable evidence remains blocking and cannot be
+dispositioned through this compatibility path. The CLI
 exits nonzero when evidence is incomplete, even when the valid-receipt count is
 zero. Current SDK implementations always emit the new field, while its optional
 type preserves structural compatibility for existing typed adapters and test
-fixtures. `runMergeReceiptReport` remains the compatible valid-only report.
+fixtures. A structurally valid preferred-era history summary that contains its
+complete privacy-safe receipt evidence is accepted in place: health counts it
+as `accepted_legacy_merge_receipt_references` and does not demand an external
+receipt file that the older writer never created. Incomplete, contradictory, or
+modern summaries still fail closed. `runMergeReceiptReport` remains the
+compatible valid-only report.
 
 ## Cross-branch id collision safety
 
@@ -165,7 +225,8 @@ Serialized source claims are ignored. Receipt readers validate the complete
 bounded schema, safe identifiers, filename and item-path identity, timestamps,
 and bounded decision structure before a sidecar enters health or
 reconciliation. Reads use size-preflighted, no-follow regular-file descriptors;
-durable decisions must retain hash-only values. Qualifying durable-only receipts
+durable decision values must conform to the declared bounded-inline policy or
+remain hash-only. Qualifying durable-only receipts
 are reloaded from the authoritative store and accepted only after exact canonical
 item path, declared-field, and merged-value hash verification. Legacy receipts,
 receipts whose declared fields disagree with their hashes, same-item tampering,
@@ -173,16 +234,19 @@ and drift on unrelated items fail closed to the normal `pm history-repair`
 guidance. Health indexes authoritative evidence once by item and reconciliation
 uses the same per-item groups with a fixed receipt-only worker pool, so committed
 sidecars cannot amplify drift scans into unbounded parallel repair work.
-The machine-executable remediation names the apply command because `--dry-run`
-returns a successful preview without changing the red health state. Operators
-may still run the documented dry-run first; agents that execute the remediation
-field verbatim perform the settlement instead of entering a successful no-op
-loop.
+The machine-executable remediation for a missing receipt reference names
+`pm merge reconcile --dry-run`. It never publishes `--force` as an executable
+hint: the human-readable summary explains that exact eligible pre-durable
+coordinates may be dispositioned by a separately reviewed force pass. Ordinary
+pending lossless receipts retain their unforced apply remediation.
 Apply-mode reconciliation repeats the same proof against the exact
 item snapshot used by the audited history rewrite. The audit event and
 settlement include only the individually proven receipt id, so one valid receipt
 cannot authorize an untrusted same-item sibling. Failed or unproven receipts
 remain pending unless the coordinator explicitly reviews and supplies `--force`.
+Snapshot verification accepts both the current presence-domain digest and the
+legacy version-1 scalar digest, so already-written receipts remain repairable;
+new receipts always use the collision-free presence-domain scheme.
 Receipts with discarded scalar values retain the distinct
 `merge_decisions_unreviewed:<n>` finding. Matching authoritative hash proof
 allows those receipts to settle without `--force`; without qualifying proof,
@@ -192,6 +256,15 @@ an unforced apply command that clears `merge_decisions_unreviewed` when the
 receipt proves the exact current merged values. This prevents routine repair
 from hiding unfinished reconciliation while avoiding redundant force for an
 already-proven canonical snapshot.
+The same `--force` boundary also handles an unrecoverable pre-durable
+clone-local-only history reference. Preview and apply results expose
+`missing_history_references_before`, `legacy_disposition_eligible`,
+`legacy_disposition_recorded`, and `missing_history_references_after`. When
+coordinates exceed the bounded health response, explicit result guidance
+requires repeated dry-run and reviewed force passes until health no longer
+reports truncated coordinate details and the remaining count is zero. An apply
+result cannot return `ok: true` while any missing reference or truncated
+evidence remains.
 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
@@ -233,6 +306,29 @@ keeps version incompatibility distinct from item corruption and is tracked by
 [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon) and
 [pm-2qahia](../.agents/pm/issues/pm-2qahia.toon).
 
+New history events also carry `record_hash_version` and `record_hash`. Unlike
+the item anchors, the record hash covers the complete immutable event: author
+and agent provenance, timestamp, operation, message, context, patch, item-hash
+epoch, and before/after anchors. A record that carries only one envelope field,
+uses an unsupported record epoch, or changes after sealing fails verification.
+Entries created before this envelope remain readable as explicit
+`item_state_only` coverage; they are not presented as record-authenticated.
+
+Every maintenance rewrite verifies a present record hash before changing the
+stream and reseals the output. When anchors or patch representation change, the
+entry's append-only `reanchor_evidence` retains the prior anchors, item epoch,
+patch digest, and prior record envelope. Lenient repair additionally retains
+the complete replaced patch operations. `verifyHistoryRewriteEvidence()`
+reconstructs every available prior envelope and rejects a record that was
+modified and merely resealed after maintenance. Redaction never copies sensitive patch
+values into new evidence: it keeps the digest and drops a retained patch if the
+patch itself matched a redaction rule. Compaction baselines retain the pruned
+entry count and ordered stream digest plus an explicit
+`individual_pruned_entries_require_pre_compaction_stream` limitation. A holder
+of the pre-compaction stream can therefore validate the checkpoint, while the
+post-compaction stream does not falsely claim that it can reconstruct content
+that was intentionally pruned.
+
 ## Delete versus modify policy
 
 A delete on one branch and an edit on another is not safely resolvable by a generic file driver. The merged workspace must not silently resurrect the item. `storage_integrity` reports the live document plus delete-terminated history as a hard finding. The coordinator chooses one policy explicitly:

package/docs/README.md

@@ -63,6 +63,7 @@ pm guide release --json
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
+- [SDK Agent Environments](AGENT_ENVIRONMENTS.md) - calibrated observations, total verdicts, isolated episodes, and an executable public-SDK environment.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
 - [Defect Recurrence and Boundary Evidence](DEFECT_RECURRENCE.md) - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.
@@ -80,6 +81,7 @@ pm guide release --json
 - [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
+- [SDK execution and recovery contracts](SDK_EXECUTION_CONTRACTS.md): schema-driven scheduling, handoff, and command recovery.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.
 - [Codex Plugin](CODEX_PLUGIN.md) - native MCP plugin install, tools, skills, and safety notes.
 - [Native ChatGPT and Codex Plugin Implementation Plan](CHATGPT_CODEX_PLUGIN_IMPLEMENTATION.md) - official-source

package/docs/RELEASING.md

@@ -30,7 +30,10 @@ 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).
+[pm-b9g2cs](../.agents/pm/issues/pm-b9g2cs.toon), and exact-tag changelog
+stabilization by [pm-e63v1x](../.agents/pm/issues/pm-e63v1x.toon). Dual-phase
+package sizing around Sentry injection is tracked by
+[pm-llbnua](../.agents/pm/issues/pm-llbnua.toon).
 
 ## Version Policy
 
@@ -333,7 +336,12 @@ The static phase includes `pnpm sdk:surface:check`,
 `pnpm benchmark:transport:check`. The packaging phase runs
 `pnpm quality:package-artifact`, which evaluates npm's actual packlist against
 the committed unpacked-size, file-count, required-runtime-file, and forbidden
-source-map budgets. Additive SDK exports require a reviewed
+source-map budgets. Release additionally reruns the packlist gate immediately
+after Sentry debug-ID injection and before any Sentry upload or finalization,
+using the separately committed `sentry-injected` ceiling. CI constrains the base
+build, publication constrains the exact mutated artifact users install, and a
+rejected package cannot leave finalized observability artifacts. Additive SDK
+exports require a reviewed
 snapshot refresh. A removal or semantic signature change fails until the
 maintainer supplies
 `pnpm sdk:surface:update -- --acknowledge-breaking "<release rationale>"`;
@@ -353,23 +361,27 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
+- manual `workflow_dispatch` by tag for recovery. An isolated anonymous exact-version probe keeps already-published recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery preserves the reviewed package gate and budget in runner-temporary storage before checking out that exact tagged source. The controls inspect the untouched tagged package without becoming part of it, so recovery applies the current fail-closed distribution policy while retaining the original version guard and immutable package bytes.
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
 - build, clone-local merge-driver installation, typecheck, test, and coverage
 - generated changelog verification and `pm-changelog` installation before the
   tracker-bearing static gate, so a clean checkout does not misclassify the
-  managed extension's linked files as missing. Recovery of an unpublished
-  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
-  canonical package script and fails if that operation changes any other
-  tracked source path (apart from managed-extension install metadata).
+  managed extension's linked files as missing. Every exact-tag source,
+  including an ordinary tag push and recovery of an unpublished immutable tag,
+  regenerates only `CHANGELOG.md` with the tagged checkout's canonical package
+  script and fails if that operation changes any other tracked source path
+  (apart from managed-extension install metadata). Reviewed `main` recovery
+  sources retain the non-mutating drift check.
 - 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; 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
+- a base npm pack dry run, optional Sentry debug-ID injection, a second
+  `sentry-injected` packlist budget over the exact publishable bytes, and only
+  then optional Sentry release metadata/upload/finalization and the npx tarball
+  smoke test
 - generated release notes from changelog plus sanitized tracker metadata
 - artifact uploads
 - `npm publish --access public --provenance --tag latest`, skipped on retry
@@ -458,8 +470,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   the existing immutable tag, reapplies the version guard, installs the managed
   changelog extension, regenerates the package changelog with the tagged
   checkout's canonical policy under a tracked-path mutation guard, and permits
-  first publication only from that tagged source. Other registry failures stop
-  before source selection or publication.
+  first publication only from that tagged source. Ordinary tag-push releases
+  use the same guarded regeneration because their tag did not exist when the
+  release commit's changelog was prepared. Other registry failures stop before
+  source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.

package/docs/SDK_CONTEXT_EVIDENCE_CONTRACTS.md

@@ -1,6 +1,6 @@
 # SDK Context and Evidence Contracts
 
-Tracked by [pm-gok2km](../.agents/pm/issues/pm-gok2km.toon), [pm-zryb9d](../.agents/pm/issues/pm-zryb9d.toon), [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon), [pm-hfqju5](../.agents/pm/issues/pm-hfqju5.toon), [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon), and [pm-v0a0un](../.agents/pm/issues/pm-v0a0un.toon).
+Tracked by [pm-gok2km](../.agents/pm/issues/pm-gok2km.toon), [pm-zryb9d](../.agents/pm/issues/pm-zryb9d.toon), [pm-qckpnq](../.agents/pm/issues/pm-qckpnq.toon), [pm-hfqju5](../.agents/pm/issues/pm-hfqju5.toon), [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon), [pm-v0a0un](../.agents/pm/issues/pm-v0a0un.toon), [pm-7wzb6d](../.agents/pm/issues/pm-7wzb6d.toon), [pm-mg13iz](../.agents/pm/issues/pm-mg13iz.toon), and [pm-cf4t42](../.agents/pm/issues/pm-cf4t42.toon).
 
 These contracts keep SDK context truthful, bounded, and reusable across the CLI, MCP, packages, and automation. They are designed around the project principle that project management is context management: a compact response must reveal material omissions, merge evidence must describe what actually survived, and compatibility failures must not masquerade as corruption.
 
@@ -22,7 +22,29 @@ This keeps health diagnostics and lazy runtime behavior on one ownership contrac
 
 ## Merge provenance
 
-Stable-value item merges distinguish a caller request from the outcome. Low-level item results, driver results, clone-local receipts, and privacy-safe summaries expose `requested_preference`. The actual outcome remains in each decision's `retained` and `discarded` values or hashes. New receipts do not emit the ambiguous `preferred` key; readers still ingest legacy schema-v1 receipts and normalize that key to `requested_preference`.
+Item scalar merges distinguish a caller request from the convergent outcome.
+The `latest_document_update` policy selects the branch document with the later
+`metadata.updated_at`; equal timestamps use stable value order. Low-level item
+results, driver results, receipts, and privacy-safe summaries expose
+`requested_preference` plus `requested_preference_applied: false`. Each new
+decision records `retained_side` and `resolution_basis`. New receipts do not
+emit the ambiguous `preferred` key; readers still ingest legacy schema-v1
+receipts and normalize `preferred_side` and `stable_value_order` evidence.
+
+Tracked receipt evidence uses `bounded_non_sensitive_scalars_v1`: built-in
+status, priority 0 through 4, risk/confidence/severity ordinals, and `null` may
+be included beside their verifiable hashes. Every other value remains
+hash-only. Fresh-clone consumers must branch on `value_availability` rather than
+assuming raw values exist. Invalid evidence separates `schema_invalid` from
+`identity_invalid` and adds a bounded `validation_error`, while retaining the
+legacy combined reason in the public union for source compatibility.
+
+`runMergeReconcile` also reports missing history receipt counts before and
+after the operation. With explicit `force`, it can append a narrowly matched
+audit disposition for a missing reference whose original event predates the
+durable-receipt epoch. The item id, original line, receipt id, and timestamp
+must all match, and the audit event must occur later in that history stream;
+current-era missing evidence remains blocking.
 
 ## Claim race classification
 

package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md

@@ -1,7 +1,9 @@
 # SDK Context Truth Contracts
 
 Tracker references: [pm-23xkss](../.agents/pm/issues/pm-23xkss.toon) and
-[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon).
+[pm-r8u2g6](../.agents/pm/issues/pm-r8u2g6.toon),
+[pm-79gv6q](../.agents/pm/issues/pm-79gv6q.toon), and
+[pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon).
 
 ## Agent Quick Context
 
@@ -68,3 +70,24 @@ silently route tracker files through the wrong merge behavior. Run
 This policy does not weaken storage, history, merge-fence, or pending-receipt
 checks. It only distinguishes an optional never-installed clone capability
 from a broken capability that the repository appears to rely on.
+
+## Population and Focus Are Separate
+
+`context.summary.scope` is `matching_items`: lifecycle totals describe all items
+matching the request filters and parent subtree before the focus limit, intent
+projection, and token packing. Without filters this is the workspace population.
+`active_items`, `in_progress`, `open`, and `blocked` use that same population as
+`total_items`, `closed`, and `canceled`. `open` includes active statuses other than
+in-progress; `blocked` is an overlapping classification that includes unresolved
+dependency edges as well as blocked lifecycle states.
+
+`summary.returned_focus` reports the bounded focus selection. The existing
+`high_level` and `low_level` counts describe their emitted rows. An orient or
+handoff response limited to one row can therefore still report hundreds of open
+items. `omission_receipt.summary_scope` repeats `matching_items` so a consumer
+reading projection metadata cannot confuse omitted detail with absent work.
+
+Never infer a population count from an array length. To visit individual items,
+follow the response's continuation and omission receipts. To schedule work, use
+the shared [execution contracts](SDK_EXECUTION_CONTRACTS.md), which keep human
+input, gates, and containers visible without dispatching them by default.

package/docs/SDK_EXECUTION_CONTRACTS.md

@@ -0,0 +1,105 @@
+# SDK Execution and Recovery Contracts
+
+Tracker references: [pm-08mt4k](../.agents/pm/issues/pm-08mt4k.toon),
+[pm-ugld](../.agents/pm/issues/pm-ugld.toon),
+[pm-2bqgs7](../.agents/pm/issues/pm-2bqgs7.toon),
+[pm-u4t9gp](../.agents/pm/issues/pm-u4t9gp.toon), and
+[pm-bfa1ob](../.agents/pm/issues/pm-bfa1ob.toon).
+
+## Declare Who Can Execute a Type
+
+Custom settings definitions and package `defineItemType` definitions accept
+`execution_role: "agent" | "human" | "gate"`. An omitted role defaults to agent
+execution; built-in Decision and Milestone types default to human and gate,
+respectively. A definition can override a built-in role. Aliases resolve through
+the type registry, and invalid roles are rejected rather than silently enabling
+execution.
+
+Package authors can declare a review checkpoint alongside the rest of their item
+type definition:
+
+```ts
+import { defineItemType } from "@unbrained/pm-cli/sdk/authoring";
+
+export const checkpoint = defineItemType({
+  name: "Checkpoint",
+  folder: "checkpoints",
+  aliases: ["checkpoint"],
+  execution_role: "gate",
+});
+```
+
+`computeActionabilityReport` is the pure SDK primitive: it accepts candidates,
+the surrounding item corpus, a status registry, and an optional item type
+registry. It resolves both forward `blocked_by` and reverse `blocks` edges,
+terminal prerequisites, active descendants, and execution roles. Its result
+contains ready leaves, blocked leaves, human decisions, gates, and containers.
+`selectActionableEntries` applies explicit dispatch opt-ins to that report;
+ownership and ranking remain the responsibility of the caller. The selector
+returns `ready`, `decisions`, and `gates`: eligible opted-in containers enter
+`ready`, subject to their execution role. Read `report.containers` for the full
+classified container worklist; the selector does not return a separate
+`containers` property.
+
+Integrations that construct an `ActionabilityReport` themselves must now provide
+the `containers`, `decisions`, and `gates` arrays. Prefer computing the report
+through the SDK so these classifications stay consistent with dependency and
+schema rules. Existing callers may omit the new selection options and type
+registry argument.
+
+## Read Every Scheduling Bucket
+
+`pm next` exposes `ready`, `decision_needed`, `gate_needed`, `containers`,
+`blocked`, and `held_by_others`. Summary counts describe the full matching
+buckets; each bounded worklist has truncation totals when needed. The row
+contract advertises the new gate and container collections to generic consumers.
+Intent budgets compact these worklists along with the other scheduling rows.
+Final-delivery feedback records their visible identifiers so recursive context
+improvement observes what the caller actually received.
+A workspace containing only outcome gates returns no recommendation and explains
+how to inspect or explicitly include gates.
+
+`--include-decisions`, `--include-gates`, and `--include-containers` opt into
+held-out work for both `next` and `claim --next`. The SDK and MCP use
+`includeDecisions`, `includeGates`, and `includeContainers`. These options do not
+bypass unresolved blockers, blocked lifecycle states, or ownership checks.
+Context places gates, human work, and containers in high-level context rather
+than agent execution detail. Population summaries retain all matching work.
+
+## Stop Work Explicitly
+
+`release` relinquishes ownership and preserves status. When an in-progress item
+is released (using the configured workflow status), its result includes `released_unclaimed_in_progress` and a concrete
+`pm pause-task <id>` suggestion. Use `pause-task` when the intended operation is
+to stop work and return it to the configured open state. Consumers should not
+interpret an ownership release as evidence that work has stopped.
+
+## Recover from Command Mistakes
+
+Unknown commands direct the caller to `pm --help --all`, the complete core
+command surface. `pm tests <id>` is an executable alias of `pm test <id>`.
+Positional item operands are accepted in help requests, including hybrid
+commands such as `pm files <id> --help --json`; invalid child command names still
+produce usage errors.
+
+With `--token-accounting`, JSON refusals carry the same serialized-output
+accounting used by successful commands. Accounting is attached after diagnostic
+projection and recalculated if extension failures enrich the refusal. The
+receipt measures the emitted diagnostic, including its own receipt overhead.
+Recovery metadata retains the actual invocation, including the accounting flag.
+The executable transcript gate predicts that transport change independently and
+rejects any other payload drift. It also verifies that the accounting-off
+attempted command agrees with its normalized arguments before projection.
+Detailed recovery evidence must contain argument and provided-field arrays.
+Compact recovery is accepted only when the transcript explicitly declares and
+verifies that mode; its advertised retry still executes as a separate step.
+Serialized JSON refusals use the SDK `writeStderr` transport primitive so an
+`error_format` text override cannot replace a measured machine payload.
+Human-readable error formatting remains customizable through `error_format`.
+
+The flag-invocation gate compares registered executable options against SDK
+contracts without filtering out undeclared observations. An option missing from
+the contract and a root command missing a resolver both fail the gate. A seeded
+undeclared option is a mandatory negative control. Contract snapshots, MCP
+parameter declarations, help, and completion are regenerated from the shared
+contract tables.

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -2,7 +2,9 @@
 
 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). Refusal reachability and
+[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), with forward history-epoch
+protection tracked by
+[pm-aka8m7](../.agents/pm/issues/pm-aka8m7.toon). Refusal reachability and
 recovery completeness are tracked by
 [pm-elmpav](../.agents/pm/features/pm-elmpav.toon),
 [pm-185870](../.agents/pm/issues/pm-185870.toon), and
@@ -29,6 +31,20 @@ 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 boundary is bidirectional for history storage. A current runtime also
+refuses a mutation when any package declaration or lockfile pin cannot select a
+runtime that reads the writer epoch. Every manifest section is evaluated, so a
+newer permissive declaration cannot hide an older exact pin. Upper-bounded
+ranges that exclude the first compatible reader also fail closed, including
+inclusive hyphen ranges. Disjunctive ranges evaluate each alternative, so one
+branch that can select a compatible reader keeps the declaration writable. The
+original incompatible declaration is preserved in the diagnostic rather than
+being reduced to its representative lower bound. The typed
+`project_runtime_history_epoch_incompatible` error reports the writer epoch,
+the incompatible declaration, its redaction-safe source, and the minimum
+upgrade. Reads remain available, and the same emergency override is reserved
+for an intentionally coordinated fleet migration.
+
 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,

package/docs/TESTING.md

@@ -146,6 +146,11 @@ boilerplate summaries are rejected.
 
 ## TOON Storage Round-Trip Gate
 
+History-only lifecycle reconstruction and recovery contracts are described in
+[History durability and recovery](HISTORY_RECOVERY.md). Their integration suite
+is part of the required all-source test run and compares historical projections
+against independently captured item files, including after removing those files.
+
 TOON item serialization is a fail-closed storage boundary. Before returning
 bytes to any create, update, merge, migration, or package caller, pm decodes the
 new `@toon-format/toon` output and compares it with the JSON-like canonical