@unbrained/pm-cli 2026.8.15 → 2026.8.17

package/docs/CONTEXT_INTEGRITY_CONTRACTS.md

@@ -0,0 +1,58 @@
+# Context Integrity Contracts
+
+Tracker references: [pm-4fwgaz](../.agents/pm/issues/pm-4fwgaz.toon), [pm-qqoumq](../.agents/pm/issues/pm-qqoumq.toon), [pm-fpdk37](../.agents/pm/issues/pm-fpdk37.toon), [pm-jn1x30](../.agents/pm/issues/pm-jn1x30.toon), and [pm-0wfdim](../.agents/pm/issues/pm-0wfdim.toon).
+
+## Agent Quick Context
+
+Project management is context management. A successful read or analysis must not silently erase an item's identity, reinterpret a reference, reverse a relationship, accept an ignored compatibility spelling, or rewrite history into a format an older supported CLI cannot read. These rules are implemented in shared SDK/core primitives so the CLI, packages, extensions, and MCP hosts inherit the same behavior.
+
+## Sparse Read Identity
+
+`pm get <id> --fields ...` always returns `item.id`, even when `id` was not explicitly requested. Explicitly requested collection metadata is materialized as an empty array when absent. This distinguishes “the requested collection is empty” from “the field was not read” without forcing callers to request a larger projection.
+
+```bash
+pm get pm-example --fields comments,notes,learnings,tests,test_runs,docs,plan_steps,plan_decisions,plan_discoveries,plan_validation --json
+```
+
+The result retains the canonical ID and every requested empty group, including planning and test-run collections. The public `GetResult` type requires `item.id`, so SDK consumers do not need an impossible missing-identity branch. Unrequested groups remain omitted, preserving the token-saving projection contract.
+
+## Extension Manifest Compatibility
+
+Extension manifests use the canonical top-level `pm_min_version` and optional `pm_max_version` fields. `compatibility.pm`, `engines.pm`, or other alternate spellings do not establish the loader's pm version floor.
+
+`checkExtensionManifestCompatibility` now performs a closed top-level schema inspection before evaluating bounds. It reports deterministic advisory findings for unknown keys and independently reports when both canonical bounds are absent, including for an otherwise recognized manifest. A recognized `compatibility` spelling includes `suggested_key: "pm_min_version"`. Runtime discovery emits matching `extension_manifest_*` warnings, which means `pm extension doctor` cannot silently report a clean manifest after discarding an unknown compatibility block or after receiving no compatibility intent at all.
+
+Warnings are advisory; malformed or unmet canonical bounds retain their existing blocking behavior.
+
+## Lossless Remote Documentation Links
+
+`pm docs <id> --add` accepts structured `path=...,scope=...,note=...` values, bare paths, Markdown links, and CSV label/URL pairs:
+
+```bash
+pm docs pm-example --add '[Pull request](https://github.com/org/repo/pull/42)'
+pm docs pm-example --add 'Issue report,https://github.com/org/repo/issues/17'
+pm docs pm-example --add 'Query evidence,https://example.com/report?fields=id,status'
+pm docs pm-example --add '[Nested path](https://example.com/report_(final))'
+```
+
+Each example creates one project-scoped documentation reference. The first comma separates a CSV label from the complete URL remainder, and balanced parentheses inside Markdown destinations remain part of the destination. The URL is preserved byte-for-byte as the path and the label becomes the note. File-link parsing is unchanged, and ordinary comma-separated bare document paths continue to expand as before.
+
+## Direction-Locked Graph Impact
+
+Dependency storage is oriented from the item that declares a relationship (`source`) to the referenced item (`target`). Impact analysis uses that stored orientation even for associative kinds:
+
+- `incoming` follows source items that point at the current target: dependents and requesters.
+- `outgoing` follows targets referenced by the current source: prerequisites and context dependencies.
+- `both` is the deterministic union of the complete incoming and outgoing traversals. Each branch keeps its starting direction; traversal never reverses through an associative edge halfway through a path.
+
+This prevents a shared `related` item from bridging an incoming impact query into an unrelated epic. Rows retain shortest explanation paths, bounded pagination, truncation, and query-cost receipts.
+
+## Cross-Version History Epochs
+
+History writers using item-hash epoch 2 always emit `item_hash_version: 2`. An entry without an explicit epoch is therefore legacy epoch 1 when the entire stream is implicit, including documents whose hashes happen to be identical under both algorithms. A supported explicit epoch becomes authoritative from its marker forward, so earlier unversioned entries retain both legacy and transitional candidates while a trailing ambiguous hash cannot downgrade the marked epoch. Verification and repair no longer guess a different epoch from the last ambiguous entry.
+
+Repair keeps implicit legacy streams implicit and byte-stable when no drift exists. Unsupported explicit epochs still fail with a typed `unsupported_item_hash_version` diagnostic instead of being rewritten.
+
+## Verification Boundary
+
+The regression suite covers each contract at its public SDK or command boundary. Release verification additionally installs the packed package into a temporary project and exercises sparse reads, remote docs, graph impact, extension diagnostics, and history repair without touching the repository tracker.

package/docs/DEFECT_RECURRENCE.md

@@ -0,0 +1,134 @@
+# Defect Recurrence and Boundary Evidence
+
+Tracked by [pm-1qkivy](../.agents/pm/features/pm-1qkivy.toon), [pm-rtn5h6](../.agents/pm/tasks/pm-rtn5h6.toon), [pm-0pzgit](../.agents/pm/tasks/pm-0pzgit.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+
+## Agent Quick Context
+
+`pm` treats project management as context management. A resolved defect is therefore not only a closed item: it is durable context that should select the checks most likely to prevent the same failure from recurring.
+
+The public SDK now provides three composable contracts:
+
+- a captured-boundary registry that rejects self-generated fixtures, unsafe samples, missing samples, and expired waivers;
+- a defect-evidence ratchet that requires a typed escape class plus a gate improvement or reviewed, expiring waiver on new terminal defects;
+- a versioned recurrence index that maps proposed files, packages, PM items, tags, and error codes to shared local and hosted checks.
+
+The CLI and MCP use the same SDK action path. Repository policy can be replaced by a package or workspace policy without changing the analyzer.
+
+## Public SDK
+
+Import the governance surface from the package root or the narrow governance entrypoint:
+
+```ts
+import {
+  analyzeDefectChangeRisk,
+  buildDefectRecurrenceIndex,
+  evaluateBoundaryFixtures,
+  evaluateDefectGateEvidence,
+  parseDefectRecurrencePolicy,
+  type DefectChangeRiskInput,
+  type DefectRecurrencePolicy,
+} from "@unbrained/pm-cli/sdk/governance";
+
+const policy: DefectRecurrencePolicy =
+  parseDefectRecurrencePolicy(serializedPolicy);
+const index = buildDefectRecurrenceIndex(policy, pmItems, {
+  previous_index: previousIndex,
+  changed_item_ids: changedItemIds,
+});
+const change: DefectChangeRiskInput = {
+  files: ["src/sdk/governance/assurance-action.ts"],
+  item_ids: ["pm-1qkivy"],
+};
+const report = analyzeDefectChangeRisk(index, change, { limit: 25 });
+```
+
+The index and report are deterministic. `policy_fingerprint` identifies the versioned policy; `index_fingerprint` also covers the sparse PM item-to-family contributions. Continuation cursors bind to the latter, so a cursor cannot silently continue against changed context.
+
+Each report explains its exact matching signals, returns deduplicated local and hosted checks, and includes a small cost receipt. Package authors may keep their own recurrence policy and feed the same SDK from a custom command, extension, CI adapter, or application.
+
+## CLI and MCP Action
+
+`assurance risk` accepts one JSON request through the same `definition` transport already used by SDK and MCP hosts:
+
+```bash
+risk_request=$(jq -cn \
+  --slurpfile policy config/defect-recurrence-policy.json \
+  '{policy:$policy[0],change:{files:["src/sdk/governance/assurance-action.ts"],item_ids:["pm-1qkivy"]},limit:25}')
+pm assurance risk --definition "$risk_request" --json
+```
+
+The result uses `items` as its bounded row collection and publishes `.items[]` as the stable selector. When `next_cursor` is present, submit it in the next request. A stale or malformed cursor fails rather than restarting from an ambiguous offset.
+
+Use `pm assurance risk` for an operator or agent decision. Use the pure SDK functions when a package already owns the item projection, wants to preserve an incremental index, or needs to combine risk with another domain model.
+
+### TypeScript compatibility
+
+The exported `ASSURANCE_ACTIONS` tuple and `AssuranceActionResult` union now include `risk` and `DefectChangeRiskReport`. This is additive at runtime, but TypeScript consumers with an exhaustive action or result switch must add the new branch. The SDK surface snapshot records that source-compatibility change explicitly.
+
+## Policy Model
+
+The repository example is [config/defect-recurrence-policy.json](../config/defect-recurrence-policy.json). Every family declares:
+
+- a stable id, monotonic version, title, and accountable PM item;
+- one of `production_defect`, `nightly_regression`, `scanner_finding`, or `review_caught_late`;
+- file, package, item, tag, or error-code triggers;
+- local and hosted checks selected from the same policy;
+- a negative-control change that must select the family;
+- historical PM items that justify the family;
+- maximum escape-rate and false-positive-rate budgets.
+
+Repository policy validation rejects duplicate ids, absent historical examples, missing family negative controls, invalid taxonomy values, and budgets outside zero through one. Deterministic sorting makes the serialized policy merge-friendly.
+
+## Defect Evidence on PM Items
+
+Projects can register the structured fields without changing the SDK:
+
+```bash
+pm schema add-field escape_class \
+  --type string \
+  --commands create,update,list,search,context \
+  --description "Defect escape taxonomy"
+pm schema add-field gate_evidence \
+  --type object \
+  --commands create,update,list,search,context \
+  --description "Gate improvement or explicit waiver evidence"
+```
+
+`gate_evidence` accepts one of these dispositions:
+
+- `gate_added` and `gate_strengthened` require `gate_id`, a runnable `negative_control`, non-empty `local_checks` and `hosted_checks`, and an accountable `owner`;
+- `explicit_waiver` requires an accountable `owner`, a concrete `waiver_reason`, and a future `waiver_expires_at` timestamp.
+
+The evidence epoch lets an adopting project ratchet new closures immediately while backfilling historical items deliberately. A valid `completed_at` is authoritative, `closed_at` is the compatibility fallback, and timestamp-less items created after the epoch fail closed; timestamp-less items created before the epoch remain explicitly grandfathered. Reports keep historical escape-class and disposition counts visible even before those older items become closure blockers.
+
+## Captured Boundary Fixtures
+
+The repository inventory is [config/boundary-fixtures.json](../config/boundary-fixtures.json). Each externally produced or consumed value must carry either:
+
+- a committed JSON sample with `capture_source` set to `captured_redacted` or `captured_verbatim`, capture provenance, explicit redactions, input, and observed output; or
+- an explicit reason, owner, and future expiry for a boundary that cannot yet be captured safely.
+
+The evaluator rejects a `self_generated` source because a fixture created by the same implementation cannot reveal disagreement with an external format. It also scans committed JSON for common home-directory, package-token, GitHub-token, and private-key patterns.
+
+The Claude Code directory-slug fixture is consumed directly by the author-provenance test. The npm, GitHub Actions, Git commit, and Sentry samples preserve real field shapes while replacing identifiers, paths, URLs, and user data.
+
+## Repository Gate
+
+Run the complete local gate after building:
+
+```bash
+pnpm quality:defect-evidence
+node scripts/release/defect-evidence-gate.mjs --negative-control --json
+```
+
+The first command must pass. The negative control must exit `1` after replacing a captured sample with a forbidden source and adding a terminal defect without evidence. Focused provider modes are available as `--boundary-only`, `--evidence-only`, and `--policy-only`.
+
+`repository-defect-evidence-required` is part of the blocking `repository-static-quality` assurance composition. That makes local and CI behavior share the same provider result, assertion negative control, enforcement, and immutable verdict semantics.
+
+## Recovery Producer Census
+
+`censusPmRecoveryReferenceProducers` scans complete source files for static object-literal recovery fields. It ignores type literals, destructuring patterns, labels, comments, strings, templates, and regular expressions. Aliases such as `candidate_commands`, nested `fallback_candidates[].command`, `next_best_command`, `retry_command`, and `suggested_next_steps` normalize to the same six public recovery kinds used by executable reachability verification.
+
+The census fails when a kind has no producer or when a recovery-like envelope field lacks a typed contract. The integration gate scans every `src/**/*.ts` producer; the existing real-entrypoint corpus then executes or resolves every normalized kind and proves recovery, replacement, or behavior-preserving semantics.
+
+This separation is intentional: the producer census prevents silent omissions as source grows, while entrypoint execution proves that a reference is not merely syntactically present.

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -1,6 +1,6 @@
 # Dependency-kind contract
 
-Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon)
 
 Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
 
@@ -15,6 +15,16 @@ Dependency rows have one canonical stored spelling per relationship meaning. Com
 
 The SDK relationship registry is authoritative. `canonicalizeRelationshipKind()` rejects unknown spellings, while `resolveCanonicalRelationshipKind()` supports validation flows that need an undefined result. `pm contracts` publishes `relationship_kind_contracts` with canonical names, aliases, inverses, and ordering/hierarchy semantics.
 
+`recurs_from` has no alias: a later occurrence points to an earlier occurrence.
+It is persistent after both items become terminal and carries temporal identity,
+not execution precedence. `supersedes` keeps replacement semantics, while
+`duplicate_of` remains item-level record identity rather than an edge between
+distinct events. Local create, update, and update-many mutations compare the
+endpoint `created_at` values before persistence and reject equal or reverse
+chronology with `dependency_temporal_order_invalid`; explicit cross-workspace
+references remain external because their target metadata is not locally
+available.
+
 ## Direction and actionability
 
 `blocked_by` and `blocks` are inverse storage directions with identical scheduling meaning:
@@ -26,6 +36,6 @@ Readiness, `pm next`, context blocker summaries, `pm list-blocked`, downstream `
 
 ## Legacy observability
 
-`pm deps` returns `legacy_alias_counts` for the workspace. `pm graph audit` returns the same field beside canonical `profile.edges_by_kind` counts, `profile.edge_share_by_kind` composition ratios, and the `semantic_edges`/`semantic_edge_share` context-preservation census. The semantic census counts `discovered_from`, `incident_from`, `supersedes`, and `verifies` over all deduplicated directed edges. Empty objects and zero shares are explicit, not omitted. These diagnostics are read-only; terminal history remains untouched until an explicitly governed migration is requested.
+`pm deps` returns `legacy_alias_counts` for the workspace. `pm graph audit` returns the same field beside canonical `profile.edges_by_kind` counts, `profile.edge_share_by_kind` composition ratios, and the `semantic_edges`/`semantic_edge_share` context-preservation census. The semantic census counts `discovered_from`, `incident_from`, `recurs_from`, `supersedes`, and `verifies` over all deduplicated directed edges. Empty objects and zero shares are explicit, not omitted. These diagnostics are read-only; terminal history remains untouched until an explicitly governed migration is requested.
 
 Assurance `dependency_kind` measurements canonicalize both the declaration and stored row before comparing. A declaration using `related` and one using the accepted `related_to` alias therefore measure the same edge population; alias debt remains separately observable through `legacy_alias_counts`.

package/docs/README.md

@@ -54,7 +54,9 @@ pm guide release --json
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [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.
 - [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.
+- [Context Integrity Contracts](CONTEXT_INTEGRITY_CONTRACTS.md) - sparse-read identity, closed extension manifests, lossless remote docs, direction-locked graph impact, and cross-version history epochs.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context and Evidence Contracts](SDK_CONTEXT_EVIDENCE_CONTRACTS.md) - material omission receipts, scoped preflight activation, truthful merge preference, claim-race classification, and versioned history hashes.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), and [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
 
 ## Agent Quick Context
 
@@ -122,6 +122,12 @@ list-family `--no-truncate` imply an unbounded cost dimension when the caller
 does not supply `--output-budget`; they cannot silently return a budget-trimmed
 subset while claiming to return every matched row. An explicit canonical
 budget still has precedence and may request a bounded result deliberately.
+The same SDK-native rule applies to every declared complete-result spelling,
+including `contracts --full`: explicit completeness defeats only the implicit
+default ceiling. If an explicit caller budget cannot retain any useful domain
+result, the CLI still prints the parseable omission receipt but exits 2; a
+consumer therefore cannot interpret the missing command or action arrays as a
+successful empty contract.
 
 ```bash
 pm list-open --output-include id,title,status --output-limit 10

package/docs/RELATIONSHIP_GRAPH.md

@@ -1,6 +1,6 @@
 # Relationship graph semantics
 
-Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), and [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon).
+Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon), and [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon).
 
 ## Decision
 
@@ -10,7 +10,21 @@ The alternatives were rejected as follows: a closed enum cannot model applicatio
 
 ## Contract
 
-Each relationship kind declares direction, inverse, ordering and hierarchy participation, incoming and outgoing cardinality, lifecycle, aliases, payload schema, self-edge policy, and compatibility version. Built-ins normalize legacy `related_to`, `depends_on`, `child_of`, `parent_child`, `epic`, and `task` spellings. Unknown custom kinds remain importable only after their definitions are registered, preventing algorithms from guessing their meaning.
+Each relationship kind declares direction, inverse, ordering and hierarchy participation, optional temporal order, incoming and outgoing cardinality, lifecycle, aliases, payload schema, self-edge policy, and compatibility version. Built-ins normalize legacy `related_to`, `depends_on`, `child_of`, `parent_child`, `epic`, and `task` spellings. Unknown custom kinds remain importable only after their definitions are registered, preventing algorithms from guessing their meaning.
+
+`recurs_from` is the canonical recurrence relation: `new --recurs_from--> old`
+means the source is a later event with the same observable failure identity as
+the target. Its `temporalOrder: "source_after_target"` states chronology without
+making recurrence an execution-order dependency. The edge is directed,
+many-to-many, and `persistent`, so it remains valid after either endpoint closes.
+Local mutation adapters enforce that contract against both endpoint
+`created_at` values before writing the item or immutable history; equal and
+reverse timestamps are rejected, including update-many dry runs.
+It does not replace the older event (`supersedes`) and does not assert that two
+records describe one event (`duplicate_of`). Traverse recurrence families with
+`direction: "both"`; impact, paths, dominators, centrality, cut structure, and
+community detection then operate on the connected family without special-case
+labels or retyping historical replacement edges.
 
 Ordering-cycle validation considers only kinds whose registry definition sets `ordering: true`. Associative and provenance edges never block execution. Hierarchy cycles remain a separate structural check. Canonical edge identity includes kind and ordered endpoints for directed edges, or sorted endpoints for undirected edges.
 

package/docs/RELEASING.md

@@ -25,7 +25,9 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 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). Release-candidate analyzer
-provenance is tracked by [pm-u1baah](../.agents/pm/issues/pm-u1baah.toon).
+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).
 
 ## Version Policy
 
@@ -76,9 +78,10 @@ Policy:
   created, a non-`github-actions[bot]` closure of the exact bot-created
   `Auto Release blocked` issue on the same UTC day triggers one preparation
   retry
-- if today's tag already exists, blocker closure reruns and watches the exact
-  tag-driven Release workflow instead of invoking release preparation or
-  creating an ordinal replacement; an already-successful run is recorded as
+- if today's tag already exists, blocker closure bypasses release-preparation
+  provenance, dependency installation, and build work, then selects immutable
+  Release evidence across both tag-push and guarded workflow-dispatch runs; a
+  completed success is authoritative over stale failures and is recorded as
   recovered without republishing
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - before dependency installation or build, auto-release verifies that the
@@ -92,9 +95,12 @@ Policy:
 - when scheduled failures continue across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest scheduled failure
 - closing the exact bot-created `Auto Release blocked: scheduled run failed`
   issue as a maintainer or agent records a same-day retry marker, then either
-  retries preparation when no tag exists or reruns the exact existing tag's
-  Release workflow; it comments with the recovered tag on success and reopens
-  the same issue on failure. A second close on the same UTC day is refused
+  retries preparation when no tag exists or watches an active exact-tag Release
+  workflow. If only failed or missing evidence exists, it dispatches the
+  reviewed current `release.yml` from `main` with the immutable tag input; it
+  never reruns historical workflow code. It comments with the recovered tag on
+  success and reopens the same issue on failure. A second close on the same UTC
+  day is refused
   before release mutation and reported as `retry_already_attempted`, and
   workflow cleanup closures by `github-actions[bot]` are ignored.
 - after a scheduled run publishes a tag and the downstream release workflow succeeds, auto-release closes any open `Auto Release blocked` issue so the GitHub tracker reflects current release health

package/docs/SDK.md

@@ -42,6 +42,11 @@ semantic command discovery, and append-stable linked tests are tracked by
 [pm-st7wgu](../.agents/pm/issues/pm-st7wgu.toon),
 [pm-g543](../.agents/pm/issues/pm-g543.toon), and
 [pm-x2vx](../.agents/pm/issues/pm-x2vx.toon).
+The supported CLI entrypoint boundary, truthful context-intent receipts, and
+first-class recurrence relationships are tracked by
+[pm-rf120g](../.agents/pm/tasks/pm-rf120g.toon),
+[pm-3crymx](../.agents/pm/issues/pm-3crymx.toon), and
+[pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon).
 
 Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
 
@@ -90,8 +95,14 @@ barrel remains source-compatible:
 | `@unbrained/pm-cli/sdk/public-surface.json` | Published machine-readable SDK compatibility snapshot                      |
 | `@unbrained/pm-cli/sdk`                     | Compatibility aggregate containing every supported SDK export              |
 
-`@unbrained/pm-cli/cli` remains the runtime CLI module entrypoint for package
-resolution, not a typed library API. The committed
+`@unbrained/pm-cli/cli` is the supported embeddable CLI entrypoint and exports
+only `runPmCli`. Repository tests import their internal seams from source; those
+helpers are not package API. The surface snapshot records the subpath under the
+`executable_entry` classification, so any future exposure is a classified
+surface change. The bare
+`@unbrained/pm-cli` root export is recorded as an `aggregate_alias` of
+`@unbrained/pm-cli/sdk`: its symbols are not duplicated, but a retarget of its
+declaration path is a snapshot change. The committed
 [entrypoint import-cost table](performance/sdk-entrypoint-import-costs.md)
 records fresh-process latency, RSS, and reduction versus the aggregate barrel.
 Every narrow entrypoint is bundled and type-tested independently.
@@ -137,6 +148,12 @@ from every non-testing SDK subpath must be available from
 Consumers and release tooling can read the exact shipped artifact from
 `@unbrained/pm-cli/sdk/public-surface.json` without locating repository files.
 
+The denominator is the package export map itself, not a list inside the
+generator. Every `exports` entry that declares a `types` path must carry a
+classification, and `pnpm sdk:surface:check` refuses to run while any published
+code export is unclassified — so adding a public entrypoint cannot ship it
+ungoverned.
+
 ## Public Exports
 
 Source of truth:
@@ -301,6 +318,7 @@ Command/action contract exports:
 - Actionability primitives: `collectBlockedByIds`, `resolveItemBlockers`, `collectDependencyBlockedIds`, and `computeActionabilityReport` expose the same edge-aware blocked/ready definition used by `pm next`, `pm context`, and `pm list-blocked`. Embedded schedulers can therefore classify custom lifecycle schemas without importing CLI or core modules.
 - Dependency-governance primitives: `collectDanglingDependencyReferences`, `collectMissingDependencyTargetIds`, and `assembleWorkspaceRelationshipGraph` normalize hierarchy, scalar blockers, and structured dependencies into one graph while partitioning missing targets into actionable active holders, informational terminal-history holders, and the legacy `no-active-blocker` sentinel without mutating stored history.
 - Relationship graph primitives: `RelationshipKindRegistry`, `createRelationshipKindRegistry`, `assertRelationshipEdgeAllowed`, `RelationshipGraph`, `RelationshipEventLog`, `RelationshipEventStore`, `planRelationshipEventBackfill`, `buildRelationshipContext`, `buildDepsRelationshipContext`, `hierarchyAncestors`, `hierarchyDescendants`, `orderingPredecessors`, `orderingSuccessors`, `enumerateRelationshipPaths`, `auditWorkspaceRelationshipGraph`, `isOrderingRelationshipKind`, and `dependencyToRelationship` provide application-defined edge semantics, durable replay, deterministic legacy migration, bounded semantic traversal, policy-aware governance, and explainable context queries. Mutation adapters should call `assertRelationshipEdgeAllowed` with the active registry before persistence; it resolves aliases and honors custom `allowSelf` definitions while built-in self edges fail before item or history writes. `RelationshipEventLog.stream/project` and their durable-store equivalents page immutable prefixes and fold them into deterministic application state with exact version, processed-count, and as-of metadata. `RelationshipEventStore.appendBatch` validates a complete import under one cross-process lock and atomically publishes it; `skip_identical` resume mode rejects same-id semantic collisions. `RelationshipGraphAdapter`, `createRelationshipGraphSnapshot`, `syncRelationshipGraphAdapter`, `loadRelationshipGraphAdapter`, and `federateRelationshipGraphSnapshots` form the backend-neutral content-addressed projection boundary for database or remote graph packages. `MemoryRelationshipGraphAdapter`, `assertRelationshipGraphAdapterConformance`, and `createRelationshipGraphScaleFixture` give package authors a reference implementation, reusable compatibility contract, and lazy deterministic fixtures through one million nodes. See [Relationship graph semantics](RELATIONSHIP_GRAPH.md).
+- Built-in `recurs_from` records that the source is a later occurrence of the target. Its registry contract is directed, `source_after_target`, non-ordering, many-to-many, and persistent across terminal lifecycle states. Local mutation paths enforce strictly later source `created_at` metadata before item or history persistence and return structured source/target evidence when chronology is equal, reversed, or unverifiable. It therefore connects an incident family for traversal and analytics without reclassifying `supersedes` replacements or `duplicate_of` identity collapse.
 - Atomic application transactions: `commitWorkspaceTransaction` coordinates ordered, idempotent item and relationship mutations under one workspace writer lock and a durable replay journal. Interrupted work resumes from step inspection; ordinary failures append reverse-order compensations without rewriting immutable histories.
 - Multi-branch merge primitives: `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, and `runMergeReconcile` provide the same field-aware item, hash-chain-preserving history, sequence-renumbering relationship-event, key-level configuration, and audited post-merge repair-and-verify semantics as `pm merge`; `installMergeFence` and `findGitWorkspaceRoot` let custom init hosts install the same contract with explicit roots, while `buildMergeAttributePatterns`, `refreshMergeAttributeFenceIfInstalled`, and `auditMergeAttributeFence` expose fence coverage, refresh, and validation. See [Multi-Branch Merge Safety](MERGE_SAFETY.md).
 - Dependency provenance primitives: `EXTERNAL_DEPENDENCY_SOURCE_KIND`, `EXTERNAL_DEPENDENCY_SOURCE_KIND_ALIAS`, `isExternalDependencySourceKind`, and `normalizeDependencySeedId` let custom importers preserve cross-workspace dependency ids explicitly while retaining local prefix normalization for ordinary seeds. `source_kind: "external"` is the human-facing alias and persists canonically as `global`; a `blocked_by` row with that provenance is a real external predecessor, so graph governance does not require a fabricated local item or misreport `stale_lifecycle_block`. Newly created dependency rows also carry the effective `author`, `author_source` (`asserted` or `detected`), and a mutation `source_kind`; legacy rows remain readable without invented provenance. Tracked by [pm-6sc8jq](../.agents/pm/issues/pm-6sc8jq.toon).
@@ -348,9 +366,10 @@ rendering stay at the edge.
 Embedded hosts can also import the SDK-owned bootstrap normalization primitives
 (`normalizeBootstrapInvocation`, `parseBootstrapGlobalOptions`, and related
 contracts) when they intentionally expose pm-compatible argv. Every
-`runPmCli()` call constructs a fresh Commander graph, so extension commands,
-extension flags, and runtime schema options from one workspace cannot leak into
-the next in-process invocation.
+`runPmCli()` call constructs a fresh Commander graph and restores the host's
+existing `process.exitCode` after both successful and failed invocations, so
+extension state and CLI exit state from one workspace cannot leak into the next
+in-process invocation.
 
 ### Build a non-PM temporal domain
 
@@ -653,6 +672,20 @@ representative medium-workspace answers use the live
 negative control: the gate fails unless that deliberately unsafe request
 exceeds the default contract.
 
+Named read intents additionally return `context_intent`. The receipt separates
+the declaration (`declared_token_budget`) from the effective ceiling
+(`token_budget`) and reports their signed `token_budget_override`. Row-oriented
+reads clamp an explicit limit to the budget-derived ceiling and identify the
+binding constraint. `declaration_feasible` evaluates the useful projection
+against the declared ceiling independently of whether a lower or higher caller
+override is effective. `within_budget` evaluates that same projection against
+the effective `token_budget`, so it can legitimately differ from declaration
+feasibility. If even compacted useful output cannot fit,
+`result_omitted` is true, `estimated_tokens` retains the measured pre-omission
+size (and is therefore greater than `token_budget`), and
+`budget_exceeded.restore_with` is an executable bounded retry rather than a
+generic suggestion.
+
 Unfiltered `pm contracts` now selects the summary projection by default. It
 returns canonical commands, terse intents, the most useful flags for the core
 agent loop, per-command ceilings, and the shared output policy. Use

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), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.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), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
 
 ## Agent Quick Context
 
@@ -81,8 +81,13 @@ text. `verifyPmRecoveryReferences` accepts obligations derived from real error
 envelopes and observations produced by executing a retry, resolving a declared
 command path, or linking prose to an already executed recovery. Its report
 includes the total obligation set, pass fraction, sorted findings, and stable
-coverage buckets for `suggested_retry`, `candidate_command`, `example`, and
-`next_step`, including zero-population buckets.
+coverage buckets for `suggested_retry`, `candidate_command`, `example`,
+`next_step`, `migration_hint`, and `restore_with`, including zero-population
+buckets. `derivePmRecoveryReferenceObligations` walks emitted envelopes and
+generated read-output contracts, so tests cannot silently omit a producer
+family. Each obligation declares `recovery`, `replacement`, or
+`behavior_preserving` semantics and its proof must demonstrate the same
+promise.
 
 The repository integration corpus drives real CLI refusals, executes the
 emitted retry in a temporary tracker, compares candidate commands with the
@@ -128,17 +133,32 @@ SDK callers use `fullHistory: true`; MCP callers use `full: true`. The default s
 
 ## 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.
+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. Applying is a two-step operation: dry-run returns a deterministic SHA-256 over the complete, ordered coordinate set and every exact source-line hash; apply requires that fingerprint and refuses stale source or selection drift with `CONFLICT` exit 4 before writing history.
 
 ```bash
 pm history-author-acknowledge \
   --event _workspace:4 \
+  --dry-run
+
+pm history-author-acknowledge \
+  --event _workspace:4 \
+  --plan-fingerprint <sha256-from-preview> \
   --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 and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+Preview coordinates are bounded with `--limit`, but the fingerprint and counts always cover the complete selection. Plans distinguish already acknowledged coordinates, and apply reports `effect`, `no_effect` (exit 6), or `partial_effect` (exit 7). Bulk selection appends only newly actionable rows, while explicit coordinates may append a superseding disposition as described below. The SDK exposes `planUnknownAuthorHistoryAcknowledgment`, `resolveUnknownAuthorAcknowledgmentSelector`, and `parseUnknownAuthorHistoryEventCoordinates` so packages never need a private copy of this grammar. Health and validate map actionable unknown-author warnings directly to this append-only acknowledgment command instead of sending callers through another diagnostic loop.
+
+An explicit `--event` selection is also the append-only correction path: if a
+coordinate already has a disposition, preview marks it
+`already_acknowledged`, and fingerprint-bound apply appends a later disposition
+that supersedes the earlier attribution. Recover the original coordinates from
+`context.author_acknowledgment.events` in the applicable
+`history/_workspace.jsonl` record, preview those same coordinates, and apply the
+fresh fingerprint with the corrected author and review evidence. By contrast,
+`--all-actionable` intentionally selects only undispositioned rows; an empty
+bulk selection remains `no_effect` and never repeats existing dispositions.
 
 ## Health provider boundary
 
@@ -152,6 +172,14 @@ That agreement check reads only local history and JSON files: mismatched,
 missing, or unreadable singleton paths become bounded `history_drift` evidence
 without enabling embeddings, vector-store access, or any other provider I/O.
 
+Every SDK operation that requires a valid `_workspace` chain refuses the same
+way when verification fails. The typed `workspace_history_chain_invalid`
+conflict includes `verification_errors` in CLI JSON and SDK error context plus
+an executable `pm history _workspace --verify --json` recovery command. This
+keeps deliberate corruption tests and recoverable tracker drift out of the
+unexpected-runtime-error channel without weakening the fail-closed mutation
+boundary.
+
 Brief and summary check-only health projections use the scalar-only metadata
 reader. Validation uses collection-bearing metadata for evidence and
 relationship checks and materializes bodies only when strict history-drift

package/docs/SDK_CONTEXT_TRUTH_CONTRACTS.md

@@ -5,11 +5,11 @@ Tracker references: [pm-23xkss](../.agents/pm/issues/pm-23xkss.toon) and
 
 ## Agent Quick Context
 
-An empty tracker, a missing tracker, and an invalid tracker path are different
-states. Likewise, an optional local Git optimization and a drifted installed
-configuration are different health findings. The SDK preserves these
-distinctions so automation does not infer project truth from an ambiguous empty
-array or a generic failed verdict.
+An empty tracker, a missing tracker, an invalid tracker path, and an unreadable
+tracker are different states. Likewise, an optional local Git optimization and
+a drifted installed configuration are different health findings. The SDK
+preserves these distinctions so automation does not infer project truth from an
+ambiguous empty array or a generic failed verdict.
 
 ## Metadata Root Diagnostics
 
@@ -24,6 +24,11 @@ A missing root throws `PmCliError` with exit code `NOT_FOUND`, diagnostic code
 `tracker_root_missing`, and context reason `missing`. A regular file or other
 non-directory root throws `PmCliError` with exit code `USAGE`, diagnostic code
 `tracker_root_not_directory`, and context reason `not_a_directory`.
+An existing root that cannot be enumerated throws `PmCliError` with exit code
+`GENERIC_FAILURE`, diagnostic code `tracker_root_unreadable`, and context reason
+`unreadable`. On POSIX hosts, enumeration requires both read and directory-search
+permission: a root whose mode lacks either permission is unreadable, even when a
+privileged process could bypass those mode bits.
 
 Consumers should branch on the stable diagnostic code:
 
@@ -35,6 +40,9 @@ try {
   if (error instanceof PmCliError && error.code === "tracker_root_missing") {
     // Ask the caller to select or initialize a tracker.
   }
+  if (error instanceof PmCliError && error.code === "tracker_root_unreadable") {
+    // Repair tracker permissions before trusting any project context.
+  }
 }
 ```
 

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -45,9 +45,17 @@ 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
+existing catch boundary. The classifier accepts both symbolic Node `code`
+values and declared numeric `errno` values from `node:os.constants.errno`; this
+also recognizes platform errors that Node renders only as a number, such as a
+Linux `-122` quota failure. Non-errno failures are returned unchanged and must
 not be relabeled as environment faults.
 
+Linked-test tracker seeding uses this boundary. A required sandbox copy that
+exceeds temporary-filesystem capacity fails with a stable recovery contract,
+while linked tests whose effective context is schema avoid materializing
+tracker data at all.
+
 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

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).
+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).
 
 ## Agent Quick Context
 
@@ -353,6 +353,13 @@ The manifest records baseline bytes and estimated tokens for visible review
 deltas. Updating it cannot raise answer ceilings, which remain owned by
 `PM_COMMAND_OUTPUT_BUDGET_CONTRACTS`.
 
+The gate derives every supported harness, model, session, and provenance
+environment key from the SDK-owned harness descriptor registry. It deletes
+those host inputs before each fixture invocation, then supplies only the
+fixture's deterministic author and isolated tracker settings. Unrelated host
+environment values remain available, so the test process stays representative
+without allowing the launching agent or CI harness to change measured output.
+
 ## Linked Tests
 
 Add tests to the item that owns the work:
@@ -399,6 +406,16 @@ When a linked command is a PM tracker-read such as `pm validate`, the default mi
 `--auto-pm-context`, which keeps schema isolation for ordinary commands and routes only tracker-read PM commands
 through seeded tracker data.
 
+The runner resolves every selected command's effective context before it
+creates temporary sandboxes. Runs whose effective context is schema initialize
+only their schema roots; a non-PM command explicitly configured with
+`pm_context_mode: "tracker"` still requires tracker data. Tracker roots and item
+data are materialized only when at least one selected command requires tracker
+context. This preserves source isolation without copying an unrelated tracker
+into constrained temporary storage.
+Capacity, permission, and resource failures while seeding a required tracker
+surface as typed, path-redacted host-environment refusals with recovery steps.
+
 Use explicit modes when needed:
 
 ```bash

package/docs/TRUSTWORTHY_CONTEXT_EVIDENCE.md

@@ -61,7 +61,7 @@ Each measurement result carries `definition_fingerprint`; assertion verdicts cop
 }
 ```
 
-The semantic numerator is the sum of `discovered_from`, `incident_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
+The semantic numerator is the sum of `discovered_from`, `incident_from`, `recurs_from`, `supersedes`, and `verifies`. Audit baselines preserve the new fields, accept older snapshots with explicit zero defaults, and report signed count/share deltas.
 
 ## Health Row Predicate