@unbrained/pm-cli 2026.8.16 → 2026.8.18

package/docs/CONFIGURATION.md

@@ -156,7 +156,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 | `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
 | `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
 | `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Any other value is ignored and the context is inferred.                            |
-| `PM_TELEMETRY_HTTP_TIMEOUT_MS`        | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
+| `PM_TELEMETRY_HTTP_TIMEOUT_MS`       | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
 | `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
@@ -523,6 +523,11 @@ Fields live in `.agents/pm/schema/fields.json` with the shape `{ "fields": [Runt
       "required_on_create": false, // required only on create
       "allow_unset": true, // allow clearing via --component "" / --no-component
       "required_types": ["Task"], // only required for these item types (subset of required*)
+      "value_schema": {
+        // optional recursive semantic constraints
+        "type": "string",
+        "enum": ["frontend", "backend", "operations"],
+      },
     },
   ],
 }
@@ -541,6 +546,7 @@ Fields live in `.agents/pm/schema/fields.json` with the shape `{ "fields": [Runt
 - `allow_unset` — when `true` (default), the field can be cleared; when `false`, an explicit unset is rejected.
 - `required_types` — narrows `required`/`required_on_create` to only the listed item types.
 - `description` — surfaced in `--help`.
+- `value_schema` — optional recursive JSON-value validation applied after CLI coercion and before create/update persistence. It supports `type`, `const`, `enum`, `min_length`, `min_items`, `format: "date-time"`, object `properties`/`required`/`additional_properties`, array `items`, and exact-one `one_of` variants. This lets project-defined fields enforce domain semantics without custom command code.
 
 End-to-end example — add a required-on-create `component` string field on `Task` items:
 
@@ -561,6 +567,57 @@ End-to-end example — add a required-on-create `component` string field on `Tas
 }
 ```
 
+Object schemas can model discriminated evidence contracts. The following accepts either complete gate proof or an expiring waiver and rejects unknown keys:
+
+```jsonc
+{
+  "key": "gate_evidence",
+  "type": "object",
+  "value_schema": {
+    "type": "object",
+    "required": ["disposition", "owner"],
+    "additional_properties": false,
+    "properties": {
+      "disposition": {
+        "enum": ["gate_added", "gate_strengthened", "explicit_waiver"],
+      },
+      "owner": { "type": "string", "min_length": 1 },
+      "gate_id": { "type": "string", "min_length": 1 },
+      "negative_control": { "type": "string", "min_length": 1 },
+      "local_checks": {
+        "type": "array",
+        "min_items": 1,
+        "items": { "type": "string", "min_length": 1 },
+      },
+      "hosted_checks": {
+        "type": "array",
+        "min_items": 1,
+        "items": { "type": "string", "min_length": 1 },
+      },
+      "waiver_reason": { "type": "string", "min_length": 1 },
+      "waiver_expires_at": { "type": "string", "format": "date-time" },
+    },
+    "one_of": [
+      {
+        "properties": {
+          "disposition": { "enum": ["gate_added", "gate_strengthened"] },
+        },
+        "required": [
+          "gate_id",
+          "negative_control",
+          "local_checks",
+          "hosted_checks",
+        ],
+      },
+      {
+        "properties": { "disposition": { "const": "explicit_waiver" } },
+        "required": ["waiver_reason", "waiver_expires_at"],
+      },
+    ],
+  },
+}
+```
+
 ```bash
 pm create Task "Fix token refresh" --component auth   # stored in item metadata
 pm list --component auth                              # filter by the custom field

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

@@ -41,8 +41,8 @@ Use progressive disclosure:
 ```bash
 pm context --limit 10
 pm search "<request keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 pm install guide-shell --project
 pm guide workflows
 ```
@@ -82,8 +82,8 @@ The canonical loop is maintained in [AGENT_GUIDE.md](AGENT_GUIDE.md) — this is
 ```bash
 pm context --limit 10
 pm search "<keywords>" --limit 10
-pm list-open --limit 20
-pm list-in-progress --limit 20
+pm list --status open --limit 20
+pm list --status in_progress --limit 20
 ```
 
 2. Claim and start

package/docs/QUICKSTART.md

@@ -94,7 +94,7 @@ Useful item types:
 ```bash
 pm context --limit 10
 pm search "restore lock retry" --limit 10
-pm list-open --limit 20
+pm list --status open --limit 20
 pm claim <item-id>
 pm update <item-id> --status in_progress --message "Start implementation"
 pm update <item-id> --add-tags urgent,backend

package/docs/README.md

@@ -40,9 +40,11 @@ pm guide release --json
 - [Testing](TESTING.md) - sandbox-safe local tests and linked-test orchestration.
 - [Security Governance](SECURITY_GOVERNANCE.md) - vulnerability reporting, review discipline, property fuzzing, and OpenSSF limitations.
 - [Architecture](ARCHITECTURE.md) - contributor internals: storage, mutation flow, search, extensions, and command contracts.
+- [Noun–Verb CLI Grammar](CLI_GRAMMAR.md) - accepted command architecture, exhaustive destination census, hidden aliases, and the surface-growth gate.
 - [SDK Primitive Inventory](SDK_PRIMITIVE_INVENTORY.md) - SDK-first migration map and private-import ratchet for CLI/MCP layering.
 - [Package SDK Contract Conformance](PACKAGE_SDK_CONTRACT_CONFORMANCE.md) - authoritative public types, `typeof` module derivation, and the first-party parity gate.
 - [SDK Action and Boundary Conformance](SDK_ACTION_CONFORMANCE.md) - derived CLI/SDK/MCP action vocabulary, public-import ratchets, intent budget diagnostics, and package-runner proof.
+- [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
@@ -54,7 +56,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/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

@@ -27,7 +27,8 @@ 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), and
 authoritative blocker-recovery run selection by
-[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon).
+[pm-db8onn](../.agents/pm/issues/pm-db8onn.toon), and queued automatic
+same-day recovery by [pm-dm2vfz](../.agents/pm/issues/pm-dm2vfz.toon).
 
 ## Version Policy
 
@@ -78,11 +79,11 @@ 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 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
+- if today's tag already exists, a queued schedule or blocker closure bypasses
+  candidate preparation and accepts the immutable result only after independent
+  public-distribution evidence confirms the exact release; incomplete
+  publication continues through bounded recovery instead of being accepted
+  from tag presence alone
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - before dependency installation or build, auto-release verifies that the
   candidate has exact-commit analyzer results or an immutable tree-identical
@@ -104,6 +105,10 @@ Policy:
   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
+- workflow concurrency can leave a delayed schedule queued behind another
+  production run. The queued schedule resolves the current UTC-day immutable
+  result before candidate provenance, proves publication, and exits without
+  evaluating the generated release commit as a new candidate
 
 Pipeline entrypoint:
 
@@ -268,6 +273,25 @@ confirms that exact merge SHA, `main` base, and reviewed head. Remediate a
 refused direct-main candidate by landing the next tree-changing fix through a
 reviewed PR; never copy, synthesize, or bypass analyzer evidence.
 
+### Reviewed Delivery Closeout
+
+The reviewed delivery includes its PM evidence, item closure, and generated
+changelog. Complete those mutations on the implementation branch before merge
+whenever their evidence is already available. A pull request is not complete
+while known tracker or changelog closeout remains queued for a direct push.
+
+When a repository update genuinely depends on the merge SHA or a post-merge
+hosted result, create a normal follow-up branch from `main` and land that update
+through another reviewed pull request. Do not push `.agents/pm/**` or
+`CHANGELOG.md` closeout directly to `main`. Although tracker-only commits do not
+create package-release eligibility by themselves, the direct commit still
+becomes the default-branch head and lacks the reviewed analyzer evidence needed
+by the next release-relevant candidate. `Release analyzer readiness (main)`
+must fail closed in that state; its failure is a provenance control, not an
+analyzer approval. Restore readiness only with a tree-changing, `main`-based,
+reviewed pull request—never by copying statuses, weakening the gate, or
+synthesizing a pull-request association.
+
 ```bash
 # Read-only parity check
 pnpm release:pipeline:dry-run