@unbrained/pm-cli 2026.8.11 → 2026.8.13

package/docs/ASSURANCE.md

@@ -1,6 +1,6 @@
 # Project Assurance Primitives
 
-Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon)
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon), [pm-uhv1m5](../.agents/pm/features/pm-uhv1m5.toon), [pm-m7bb7r](../.agents/pm/features/pm-m7bb7r.toon), [pm-py7qv2](../.agents/pm/issues/pm-py7qv2.toon), [pm-33mjrw](../.agents/pm/issues/pm-33mjrw.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon)
 
 ## Agent Quick Context
 
@@ -22,20 +22,27 @@ The assurance SDK keeps those semantics independent from presentation. Commander
 
 Measurements support these built-in sources:
 
-| Source | Purpose |
-| --- | --- |
-| `items` | Count items matching status, type, tags, or an exact metadata field. |
-| `dependency_kind` | Count typed relationship edges such as `blocked_by` or `verifies`. |
-| `graph` | Select a numeric or labelled-set field from a public graph SDK result. |
-| `validate` | Select a validator check status or numeric detail. |
-| `health` | Select a health check status, numeric detail, or labelled set. |
-| `history` | Count immutable events by operation, author, harness, or model. |
-| `links` | Count items with present or missing file, test, or documentation evidence. |
-| `derived` | Combine numeric measurements with deterministic arithmetic and cycle detection. |
-| `provider` | Delegate a measurement to an explicitly supplied host/package resolver. |
+| Source            | Purpose                                                                                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`           | Count authoritative full item records matching status, type, tags, an exact metadata field, or a field `state` of `present`/`missing`.   |
+| `dependency_kind` | Count typed relationship edges such as `blocked_by` or `verifies`; accepted aliases and canonical spellings measure the same population. |
+| `graph`           | Select a numeric or labelled-set field from a public graph SDK result.                                                                   |
+| `validate`        | Select a validator check status or numeric detail.                                                                                       |
+| `health`          | Select a health check status, numeric detail, or labelled set.                                                                           |
+| `history`         | Count immutable events by operation, author, harness, or model.                                                                          |
+| `links`           | Count items with present or missing file, test, or documentation evidence.                                                               |
+| `derived`         | Combine numeric measurements with deterministic arithmetic and cycle detection.                                                          |
+| `provider`        | Delegate a measurement to an explicitly supplied host/package resolver.                                                                  |
 
 Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
 
+One workspace context memoizes identical graph operations and the shared
+validate and health reports for its lifetime. A gate may therefore project many
+fields from one authoritative audit snapshot without multiplying full-workspace
+I/O or allowing concurrent assertions to observe different tracker states.
+
+An `items` source with `field` must declare exactly one predicate: `equals` (including an explicit `null`) or `state`. `state: missing` treats an absent property, `null`, an empty string, or an empty array as missing; `state: present` selects the complement. Workspace evaluation loads full item metadata, so `files`, `tests`, and `docs` selectors measure stored evidence rather than a light projection that omitted those collections.
+
 Assertions require exactly one polarity:
 
 - `ceiling`, `floor`, `equals`, or `zero`
@@ -84,6 +91,152 @@ pm assurance remove gate release-readiness
 
 Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
 
+### Presets, derivation, and promotion
+
+List the four built-in project shapes, preview one as ordinary declarations, or apply it atomically:
+
+```bash
+pm assurance presets
+pm assurance presets software-delivery --owner pm-example
+pm assurance apply software-delivery --owner pm-example \
+  --message "Adopt the initial delivery evidence contract"
+```
+
+The preset creates measurements, assertions, and a gate in one audited transaction. Reapplying the same bundle is idempotent; an existing divergent id is refused rather than overwritten. The available shapes are `software-delivery`, `research`, `agent-evaluation`, and `operations`.
+
+Self-derivation observes active items without writing anything. Each proposal reports its active scope, population size, and observed missing-evidence ceiling. Persistence requires the explicit `--apply` flag:
+
+```bash
+pm assurance derive --owner pm-example
+pm assurance derive --owner pm-example --apply \
+  --message "Accept the observed evidence baseline"
+pm assurance promote derived-active-missing-tests-ceiling --enforcement warn
+pm assurance promote derived-active-missing-tests-ceiling --enforcement block
+```
+
+Derived assertions start at `observe`. Promotion is exactly one step (`observe` to `warn`, then `warn` to `block`) and each transition is an ordinary audited declaration mutation. There is no automatic promotion and no privileged preset execution path.
+
+## Extension Measurement Providers
+
+An extension opens the measurement vocabulary through `api.registerAssuranceMeasurementProvider`. The registration declares stable keys, parameter types, a coarse `low`/`medium`/`high` cost class, network use, a host timeout, and a resolver. It requires the `services` capability; a network provider must also declare `permissions.network: true` in `manifest.json`.
+
+This code-quality provider measures a local report without changing assertion or gate semantics:
+
+```ts
+import { readFile } from "node:fs/promises";
+import { defineExtension } from "@unbrained/pm-cli/sdk";
+
+export default defineExtension({
+  activate(api) {
+    api.registerAssuranceMeasurementProvider({
+      id: "coverage",
+      keys: {
+        lines: {
+          value_type: "number",
+          parameters: { report: { type: "string", required: true } },
+        },
+      },
+      cost_class: "low",
+      network: false,
+      timeout_ms: 2_000,
+      async resolve({ parameters }) {
+        const report = JSON.parse(
+          await readFile(String(parameters.report), "utf8"),
+        ) as {
+          total: { lines: { pct: number } };
+        };
+        return { value: report.total.lines.pct, population_size: 1, cost: 1 };
+      },
+    });
+  },
+});
+```
+
+An evaluation package can expose episode reward on the same surface:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "agent-eval",
+  keys: {
+    "mean-reward": {
+      value_type: "number",
+      parameters: { suite: { type: "string", required: true } },
+    },
+  },
+  cost_class: "high",
+  network: false,
+  timeout_ms: 120_000,
+  async resolve({ parameters }) {
+    const result = await runFrozenEvaluation(String(parameters.suite));
+    return {
+      value: result.meanReward,
+      population_size: result.episodes,
+      cost: result.steps,
+      contributors: result.regressedScenarioIds,
+    };
+  },
+});
+```
+
+An external registry provider declares its network dependency explicitly:
+
+```ts
+api.registerAssuranceMeasurementProvider({
+  id: "npm-registry",
+  keys: {
+    "dist-tag-count": {
+      value_type: "number",
+      parameters: { package: { type: "string", required: true } },
+    },
+  },
+  cost_class: "medium",
+  network: true,
+  timeout_ms: 5_000,
+  async resolve({ parameters }) {
+    const name = encodeURIComponent(String(parameters.package));
+    const response = await fetch(
+      `https://registry.npmjs.org/-/package/${name}/dist-tags`,
+    );
+    if (!response.ok) throw new Error(`registry returned ${response.status}`);
+    const tags = (await response.json()) as Record<string, string>;
+    return { value: Object.keys(tags).length, population_size: 1, cost: 10 };
+  },
+});
+```
+
+The corresponding measurement is ordinary registry data:
+
+```json
+{
+  "id": "published-tag-count",
+  "source": {
+    "kind": "provider",
+    "provider": "npm-registry",
+    "key": "dist-tag-count",
+    "parameters": { "package": "@example/tool" }
+  }
+}
+```
+
+A provider-backed gate must opt into every provider and each trigger's execution envelope. Omission refuses provider execution:
+
+```json
+{
+  "id": "release-readiness",
+  "assertion_ids": ["published-tag-count-ceiling"],
+  "triggers": ["ci", "scheduled"],
+  "provider_policy": {
+    "allowed_providers": ["npm-registry"],
+    "triggers": {
+      "ci": { "max_cost_class": "low", "allow_network": false },
+      "scheduled": { "max_cost_class": "medium", "allow_network": true }
+    }
+  }
+}
+```
+
+Before invocation the host verifies the provider allow-list, declared cost class, and network capability for the active trigger. It then validates key parameters and result shape, enforces the registered timeout, and charges the returned cost through the existing measurement ceiling. Extension tests must bind `PM_PATH` and `PM_GLOBAL_PATH` to temporary roots; never point provider fixtures at the repository tracker or a live service.
+
 ## SDK and MCP
 
 The reusable client exposes the same action grammar:
@@ -101,9 +254,9 @@ await pm.assurance({
 });
 ```
 
-For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. A host contributes provider measurements by passing stable resolver ids to `createAssuranceWorkspaceContext`; an absent resolver fails loudly. External adapters must enforce an appropriate timeout. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, the preset/derivation helpers, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. Active extension registrations are discovered automatically. Embedding hosts may additionally pass stable resolver ids and matching `provider_capabilities` to `createAssuranceWorkspaceContext`; an absent resolver or capability fails loudly. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
 
-Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, or `verdicts`. Discover the current machine contract instead of copying parameter lists:
+Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, `verdicts`, `presets`, `apply`, `derive`, or `promote`. Discover the current machine contract instead of copying parameter lists:
 
 ```bash
 pm contracts --action assurance --schema-only --json
@@ -117,10 +270,13 @@ A gate emits one object containing:
 - gate id, evaluated tree, trigger, timestamp, and dry-run status;
 - overall `pass`, `warn`, or `block` plus stable exit code;
 - every assertion's measurement, scope, population, observed value, structured bound, signed distance, enforcement, negative-control proof, cost, and contributors;
+- every assertion's `measurement_definition_fingerprint`, a SHA-256 identity for the exact declaration that produced the observation;
 - an aggregate compute receipt.
 
 Dry runs never write history. Non-dry verdicts are immutable workspace audit events and remain queryable after ordinary registry changes. Verdict reads return newest entries first and default to a bounded result; use `--limit` to select up to 1,000 matching records. A blocking verdict exits non-zero; warnings and observations remain successful while preserving their failed assertion rows.
 
+Verdicts persisted before definition fingerprints were introduced remain readable and are identifiable by the absence of `measurement_definition_fingerprint`. Registry mutations and verdict writes use the same explicit-author, configured-author, and detected-harness precedence as other SDK mutations; they do not manufacture an `unknown` author when a harness identity is available.
+
 ## Safety and Evolution
 
 - Use stable lowercase ids; prose belongs in descriptions and mutation messages.

package/docs/COMMANDS.md

@@ -19,7 +19,9 @@ pm contracts --command <command> --flags-only --json
 - Use `pm contracts --summary --json` for the cheapest command map, then narrow with command-scoped contracts.
 - Every mutation writes history.
 
-Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
+Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
+[pm-7nqo6b](../.agents/pm/issues/pm-7nqo6b.toon), and
+[pm-j1r8gl](../.agents/pm/issues/pm-j1r8gl.toon).
 
 ## Command Families
 
@@ -941,17 +943,25 @@ pm history-repair <id> --dry-run
 pm history-repair <id> --message "re-anchor legacy drift"
 pm history-repair --all --dry-run
 pm history-repair --all --message "bulk re-anchor drifted streams"
-pm activity --id <id> --limit 50
+pm activity                         # item digest for the last 24 hours
+pm activity --raw --id <id> --limit 50
 pm activity --full --id <id> --limit 50
 pm activity --full --unbounded
 pm restore <id> <timestamp-or-version>
 ```
 
 History is append-only. Restore appends a new restore event instead of rewriting old history.
-Bare `pm activity` is bounded to 20 compact rows; direct SDK calls default to
-five full rows. Every result reports total and omitted counts plus the applied
-bound. Use `--limit` for a deliberate cap, or `--unbounded` for an explicitly
-unlimited read; the two flags are mutually exclusive.
+Bare `pm activity` is an item-centric digest for the last 24 hours, bounded to
+15 most-recently-touched items. Each row joins current `id`, `type`, `status`,
+and title with the matching event count, first/last timestamps, and a bounded
+operation histogram. `activity_summary` states the effective window plus event,
+item, author, and operation counts, so an empty digest is distinguishable from
+a bounded one. Use `--raw` for the legacy compact per-event stream, `--compact`
+as its compatibility spelling, `--full` for events with patch payloads, or
+`--provenance` for patch-free provenance rows. Every mode reports total and
+omitted row counts plus the applied bound. Use `--limit` for a deliberate cap,
+or `--unbounded` for an explicitly unlimited read; the two flags are mutually
+exclusive.
 Workspace-scoped mutations to settings, schema, profiles, init state, and
 extension/package activation are recorded in
 `.agents/pm/history/_workspace.jsonl` using the same patch/hash format.
@@ -962,10 +972,21 @@ workspace auditing and is created on the first audited singleton mutation.
 
 `--diff` replays the history chain and emits, per entry, a `changes` array of `{ field, before, after }` field-level value transitions (alongside the `changed_fields` name list) — so you can see exactly what each field changed from and to without comparing snapshots. It is independent of the compact/full projection. `--field <name>` narrows the diff to a single field's transitions (implying `--diff`), answering "when did `<field>` change?" — e.g. `pm history <id> --diff --field status`.
 
-`pm stats` reports item and history totals plus per-type/per-status counts. Add `--storage` for aggregate history-stream metrics — `total_streams`, `total_lines`, `total_bytes`, the top streams by size (`largest_by_bytes`) and by depth (`deepest_by_lines`), and the global `oldest_entry`/`newest_entry` — to decide when to compact or redact streams and to plan storage:
+`pm stats` reports item and history totals plus a screen-sized lifecycle table.
+Every non-empty item type is one row with `total`, `open`, `in_progress`,
+`blocked`, `draft`, `closed`, `canceled`, and `other` counts. Empty registered
+types and statuses are suppressed and their combined count is retained in the
+`omitted_zero_buckets` scalar. The default TOON projection is gated at no more
+than 22 lines on the representative release fixture. Add `--include-empty` to
+restore every zero-filled type and status for schema-governance dashboards.
+Add `--storage` for aggregate history-stream metrics — `total_streams`,
+`total_lines`, `total_bytes`, the top streams by size (`largest_by_bytes`) and
+by depth (`deepest_by_lines`), and the global `oldest_entry`/`newest_entry` — to
+decide when to compact or redact streams and to plan storage:
 
 ```bash
 pm stats
+pm stats --include-empty
 pm stats --storage --json
 pm stats --metadata-coverage --json
 pm stats --field-utilization --json
@@ -973,7 +994,7 @@ pm stats --by-assignee --by-priority
 pm stats --by-tag --tag-prefix domain: --json
 ```
 
-For governance dashboards, `--metadata-coverage` adds a `metadata_coverage` block reporting per-field `present`/`applicable`/`percent` for `acceptance_criteria`, `estimated_minutes`, `resolution`, `tags`, and `parent` — overall and `by_type` (resolution coverage is scoped to terminal items, its only applicable population). `--field-utilization` adds a `field_utilization` block reporting `present`/`total`/`percent` for each content field (`notes`, `learnings`, `files`, `docs`, `tests`, `comments`, `deps`, `body`, `linked_command`) across all items, so under-documented content dimensions are visible at a glance and pair naturally with the `--has-*`/`--no-*` list filters for drill-down. `--by-assignee`, `--by-tag`, and `--by-priority` add a `breakdowns` block with lifecycle-bucketed rows (`open`/`in_progress`/`blocked`/`draft`/`closed`/`canceled`/`other` + `total`) per group; blank keys render an explicit `(unassigned)`/`(untagged)` label. `--by-tag` accepts `--tag-prefix` to restrict counting to a tag namespace (for example `domain:`). All of these sections are gated behind their flags so the default `pm stats` stays token-light; the per-status/per-type distributions (already in `by_status`/`by_type`) zero-fill every configured state so underutilized lifecycle states and item types are visible at a glance.
+For governance dashboards, `--metadata-coverage` adds a `metadata_coverage` block reporting per-field `present`/`applicable`/`percent` for `acceptance_criteria`, `estimated_minutes`, `resolution`, `tags`, and `parent` — overall and `by_type` (resolution coverage is scoped to terminal items, its only applicable population). `--field-utilization` adds a `field_utilization` block reporting `present`/`total`/`percent` for each content field (`notes`, `learnings`, `files`, `docs`, `tests`, `comments`, `deps`, `body`, `linked_command`) across all items, so under-documented content dimensions are visible at a glance and pair naturally with the `--has-*`/`--no-*` list filters for drill-down. `--by-assignee`, `--by-tag`, and `--by-priority` add a `breakdowns` block with lifecycle-bucketed rows (`open`/`in_progress`/`blocked`/`draft`/`closed`/`canceled`/`other` + `total`) per group; blank keys render an explicit `(unassigned)`/`(untagged)` label. `--by-tag` accepts `--tag-prefix` to restrict counting to a tag namespace (for example `domain:`). All of these sections are gated behind their flags so the default `pm stats` remains readable at first glance.
 `history-redact` rewrites matching history payloads deterministically, recomputes hash chains, and appends an auditable `history_redact` marker entry when changes are applied. Its result reports only `literal_count`, `regex_count`, `total_count`, and whether the default replacement was selected; literal values, regex source text, and replacement text are never echoed in CLI, SDK, MCP, recovery, profile, or telemetry output. Treat regex text as sensitive input because it can contain the exact material being removed.
 `history-compact` rewrites long streams into a synthetic checkpoint baseline plus a retained tail (`--before` accepts a 1-based version or ISO timestamp), re-anchors hashes, verifies integrity, and appends an auditable `history_compact` marker when applied.
 `history-compact` bulk mode (mutually exclusive with a positional `<id>`) compacts many streams in one audited pass. Select with `--ids <a,b,c>` (an explicit list — used on its own, not combined with the scan selectors below), or a scan: `--all-over <N>` (every stream with more than N entries) and/or a lifecycle filter `--closed` (terminal items only) or `--all-streams` (every stream). `--closed` and `--all-streams` are mutually exclusive. `--min-entries <N>` (default 3) skips already-compact streams; when `history.compact_policy` is enabled and `--all-over` is omitted, the policy's `max_entries` becomes the default threshold. `--before` is single-id only and is rejected in bulk mode. Each selected stream runs the same single-item compaction; one failing stream never aborts the rest — the result reports `totals` (`streams_considered`/`selected`/`items_compacted`/`items_skipped`/`items_errored`) plus one row per stream (`compacted`/`skipped` with a `skip_reason`/`errored`), and the command exits non-zero only if any stream errored.

package/docs/CONFIGURATION.md

@@ -156,6 +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_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`.                                                                   |
@@ -164,6 +165,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 Interaction rules:
 
 - `PM_TELEMETRY_DISABLED` / `PM_NO_TELEMETRY` short-circuit everything, including OTLP export, regardless of the other knobs.
+- `PM_TELEMETRY_HTTP_TIMEOUT_MS` applies only to the detached flush worker in normal use. It covers DNS, each IPv4/IPv6 connection attempt, TLS, and response completion. The upper bound preserves the 60-second worker-lock safety margin across the sequential event and OTLP phases; it does not make foreground commands wait for the network.
 - OTLP span export only happens when telemetry is enabled, `PM_TELEMETRY_OTEL_DISABLED` is off, and a traces endpoint is configured. By default spans are persisted to a bounded queue and exported by the detached, unref'd flush worker so commands exit promptly even when the traces endpoint is unreachable. `PM_TELEMETRY_INLINE_FLUSH=1` is the explicit test-oriented exception that performs the flush inline.
 - `pm health --check-telemetry --json` surfaces flush and OTLP export diagnostics (`pending_otel_spans`, `last_otel_attempt_at`, `last_otel_success_at`, `last_otel_failure_at`, `last_otel_failure_error`) and the active `env_overrides` (including `telemetry_inline_flush` and `telemetry_source_context`) so agents can self-diagnose a stalled endpoint.
 - An explicit `PM_AUTHOR` override adds a privacy-preserving agent-identity dimension to `command_start`/`command_finish` events so overridden invocations can be segmented in dashboards without leaking the raw author string. At `redacted`/`max` capture the events carry `author_context_hash` — the same installation-id-keyed one-way SHA-256 used for `pm_root_hash`/`cwd_hash`, so the same author hashes consistently within an installation but differently across installations. At `minimal` capture only a boolean `has_author_context` is emitted. The raw `PM_AUTHOR` value is never exported.
@@ -183,6 +185,13 @@ Crash and error diagnostics are reported to Sentry only when telemetry is enable
 
 > Sentry is hard-disabled under Vitest (`VITEST` / `VITEST_WORKER_ID`), so these knobs are no-ops inside the test suite.
 
+Linked commands launched by `pm test --run` default
+`SENTRY_ENVIRONMENT=test`, even when the parent process is classified as
+production. This keeps sandbox failures out of production diagnostics. An
+explicit run-level or per-test `env_set=SENTRY_ENVIRONMENT=<name>` directive
+still overrides the default when a test intentionally targets another
+environment.
+
 ## Item Storage Format
 
 TOON is the default:

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -1,15 +1,15 @@
 # Dependency-kind contract
 
-Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.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)
 
 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.
 
-| Canonical kind | Accepted legacy aliases |
-| --- | --- |
-| `blocked_by` | `depends_on`, `depends-on` |
-| `related` | `related_to`, `related-to` |
-| `parent` | `child_of`, `child-of`, `epic` |
-| `child` | `parent_child`, `parent-child`, `task` |
+| Canonical kind | Accepted legacy aliases                |
+| -------------- | -------------------------------------- |
+| `blocked_by`   | `depends_on`, `depends-on`             |
+| `related`      | `related_to`, `related-to`             |
+| `parent`       | `child_of`, `child-of`, `epic`         |
+| `child`        | `parent_child`, `parent-child`, `task` |
 
 `epic` and `task` are compatibility aliases, not item types embedded in the relationship ontology. New integrations should use `parent` or `child` and express the work classification through the item `type` field.
 
@@ -26,4 +26,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 the canonical `profile.edges_by_kind` counts. Empty objects mean no stored alias debt. 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`, `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/EXTENSIONS.md

@@ -29,6 +29,7 @@ pm install npm:package@1.2.3 --project
 pm install https://github.com/org/repo --project
 pm install --github org/repo/path --ref main --project
 ```
+
 Bundled first-party packages live under `packages/pm-*`:
 
 ```bash
@@ -38,6 +39,7 @@ pm install calendar --project
 pm install search-advanced --project
 pm install kanban --project
 ```
+
 `pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name. A bare bundled alias that also names an installed npm package reports both explicit choices in `source_resolution`; see [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
@@ -52,6 +54,7 @@ pm install npm:pm-github --project
 pm package doctor --project --detail deep --trace
 pm github validate --repo owner/repo
 ```
+
 For `pm-github`, run `pm github validate --repo owner/repo` before mutating commands; write paths require `GITHUB_TOKEN`/`GH_TOKEN` or `gh auth login`.
 
 For ecosystem maintenance, use the reusable external package smoke harness after building `dist/`:
@@ -132,7 +135,11 @@ Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/p
     "process_spawn": false
   },
   "capabilities": ["commands"],
-  "contributions": { "schema_version": 1, "commands": ["hello"], "command_handlers": ["hello"] },
+  "contributions": {
+    "schema_version": 1,
+    "commands": ["hello"],
+    "command_handlers": ["hello"]
+  },
   "activation": { "commands": ["hello"] }
 }
 ```
@@ -286,11 +293,9 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 ## Runtime APIs
 
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
-
 ```ts
 import { defineExtension } from "@unbrained/pm-cli/sdk";
 ```
-
 Common APIs:
 
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
@@ -302,6 +307,7 @@ Common APIs:
 - `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions are merged into native CLI, MCP, and SDK workspace graph assembly. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface.
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
+- `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
 - `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
 - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
 - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
@@ -312,15 +318,8 @@ Common APIs:
 - Registered command, importer, and exporter handlers receive `context.sdk`, a host-bound service bundle containing a native-action `PmClient`, `getItemAt`, and `openRelationshipEventStore`, alongside portable workspace coordinates. The client reuses the already-active extension schema context without recursively loading extensions, so package commands and data adapters can compose core lifecycle operations safely in CLI and SDK hosts.
 - An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
 
-The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only
-`hooks` and registers a default-inert `afterCommand` hook so authors can copy a
-safe lifecycle pattern without changing command output.
-
-If a package calls a `register*` API without declaring the required manifest
-capability, `pm package doctor --project --detail deep --trace` reports
-`extension_capability_missing:<name>:<capability>` and shows the exact capability
-to add before publishing.
-
+The bundled `pm-lifecycle-hooks` package is the hook exemplar: it declares only `hooks` and registers a default-inert `afterCommand` hook so authors can copy a safe lifecycle pattern without changing command output.
+If a package calls a `register*` API without declaring the required manifest capability, `pm package doctor --project --detail deep --trace` reports `extension_capability_missing:<name>:<capability>` and shows the exact capability to add before publishing.
 Inline command flags require both `commands` and `schema` capabilities. Runtime schema changes should be verified with:
 
 ```bash

package/docs/MERGE_SAFETY.md

@@ -61,7 +61,7 @@ pm merge install --dry-run --json
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream. |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                   |
 
-When both sides change the same item scalar differently, the driver writes the same stable value regardless of which branch Git labels ours or theirs, but exits nonzero. JSON leaf conflicts retain the explicit preferred-side policy. Git keeps either path conflicted so a human or coordinating agent must review the discarded value and explicitly `git add` the resolution.
+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).
 
 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).
 
@@ -133,6 +133,8 @@ pm merge reconcile --dry-run --json
 
 `history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
 
+History events now declare an item-hash epoch. The current epoch preserves linked-test insertion order; unversioned streams are verified against both the legacy sorted-test canonicalization and the order-preserving canonicalization. An unknown explicit epoch is reported as `unsupported_item_hash_version` and repair refuses to guess. This keeps version incompatibility distinct from item corruption and is tracked by [pm-2htk4p](../.agents/pm/issues/pm-2htk4p.toon).
+
 ## 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/OUTPUT_PROJECTION_CONTRACTS.md

@@ -12,7 +12,10 @@ cursor-chain amortization are tracked by
 [pm-yekkvt](../.agents/pm/issues/pm-yekkvt.toon), and
 [pm-sf31yl](../.agents/pm/issues/pm-sf31yl.toon). Trustworthy collection
 selectors are tracked by
-[pm-x710qm](../.agents/pm/issues/pm-x710qm.toon).
+[pm-x710qm](../.agents/pm/issues/pm-x710qm.toon). Default contract suppression
+and canonical TOON tables are tracked by
+[pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon) and
+[pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon).
 
 ## Agent Quick Context
 
@@ -38,12 +41,13 @@ explicit receipt with `has_omissions: false`,
 
 Mutually exclusive output modes emit only their active row collection:
 
-| Command mode                | Active row key     | Withheld group | Restore          |
-| --------------------------- | ------------------ | -------------- | ---------------- |
-| `activity --compact`        | `compact_activity` | `provenance`   | `--full`         |
-| `activity --full`           | `activity`         | none           | already complete |
-| `history` (compact default) | `compact_history`  | `raw_history`  | `--full`         |
-| `history --full`            | `history`          | none           | already complete |
+| Command mode                | Active row key        | Withheld group | Restore          |
+| --------------------------- | --------------------- | -------------- | ---------------- |
+| `activity` (digest default) | `activity_digest`     | `event_rows`   | `--raw`          |
+| `activity --raw/--compact`  | `compact_activity`    | `provenance`   | `--full`         |
+| `activity --full`           | `activity`            | none           | already complete |
+| `history` (compact default) | `compact_history`     | `raw_history`  | `--full`         |
+| `history --full`            | `history`             | none           | already complete |
 
 Inactive row keys are omitted, not zero-filled. This makes a wrong parser loud:
 reading `.activity` from compact activity now yields a missing key instead of a
@@ -57,8 +61,11 @@ integrations and built-in output cannot drift independently.
 
 ## Universal Read Rows
 
-Core read results expose a `row_contract` whether or not the current page has
-rows:
+Core read results expose `row_contract` only when callers request
+`--output-row-contract` / `outputRowContract: true`. Keeping discovery metadata
+off by default makes ordinary reads pay for project data rather than repeating
+the same selector declaration. The explicit contract remains available whether
+or not the current page has rows:
 
 ```json
 {
@@ -67,7 +74,8 @@ rows:
     "row_kind": "collection",
     "row_keys": ["items"],
     "fields": "supported",
-    "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end"
+    "jq_selector": ".row_contract.row_keys[] as $key | getpath($key | split(\".\")) | if type == \"array\" then .[] else if type == \"object\" then to_entries[] else empty end end",
+    "toon_encoding": "tabular_when_uniform"
   }
 }
 ```
@@ -80,7 +88,12 @@ collections declare every active dot-delimited path. This keeps
 nested dependency graph and relationship-context rows addressable as
 `graph.nodes`, `graph.edges`, `context.nodes`, and `context.edges` without
 duplicating them at the envelope root. Array collections produce their
-elements; object maps such as stats counts produce jq `to_entries` rows.
+elements; object maps produce jq `to_entries` rows.
+`toon_encoding: "tabular_when_uniform"` declares that an array of flat objects
+with one shared key set renders as a length-marked TOON table; mixed, nested,
+or heterogeneous arrays retain the expanded representation. Quoted,
+separator-bearing, and multiline values use the canonical TOON encoder and
+round-trip through the strict decoder.
 Commands without a row collection, including a dependency tree or leaf `get`,
 declare `row_kind: "none"`, an empty `row_keys` array, and omit `jq_selector`.
 The absence is therefore distinguishable from a legitimate empty collection.
@@ -94,8 +107,8 @@ publish a row contract.
 SDK and package authors can import `PM_READ_ROW_CONTRACTS`,
 `PM_READ_ROW_JQ_SELECTOR`, and `resolveReadRowContract` from
 `@unbrained/pm-cli/sdk`. Existing package declarations are preserved only
-when `command`, `row_kind`, `row_keys`, `fields`, and the conditional
-`jq_selector` form a structurally valid row contract; malformed declarations
+when `command`, `row_kind`, `row_keys`, `fields`, the conditional
+`jq_selector`, and any supplied `toon_encoding` form a structurally valid row contract; malformed declarations
 are replaced by the canonical built-in contract when one applies.
 
 ## Self-Describing SDK Projections

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.
+- [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.
 - [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.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.
 - [Agent UX Contracts](AGENT_UX_CONTRACTS.md) - ordering-cycle advisories, graph count units, collision safety, compact context, ownership wording, and recovery behavior.

package/docs/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), and [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.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-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), and [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon).
 
 ## Agent Quick Context
 
@@ -19,6 +19,10 @@ Row shaping follows each envelope's `row_contract.row_keys`, including
 dot-delimited nested arrays and object maps such as `graph.nodes`. Include,
 amount, repeat suppression, and cost compaction therefore operate on the same
 machine-declared rows; they do not rely on command-specific top-level keys.
+The runtime uses that declaration internally on every read but omits the
+repeated metadata from results by default. Request
+`--output-row-contract` / `outputRowContract: true` when a consumer needs the
+row paths, jq selector, and active TOON encoding contract.
 
 ## Cross-Call Context Sessions
 
@@ -46,6 +50,15 @@ tokens separately when the remaining group allowance is smaller than the
 minimum control envelope, plus the accumulated spend, remaining capacity,
 newly served items, and suppressed repeats.
 
+The carried served-item set accepts at most 10,000 identities. A receipt always
+preserves identities already present in the supplied state and retains newly
+served identities in deterministic order until that capacity is full. When a
+single read crosses the boundary, `seen_item_overflow_count` reports how many
+new identities were not carried forward; those facts remain in the current
+envelope and may be served in full again on a later read. The emitted
+`next_state` therefore always remains valid input to the next call without
+silently widening the safety bound.
+
 Session state is deliberately caller-carried: CLI processes, SDK clients, MCP
 hosts, and packages share the same deterministic primitive without a hidden
 daemon or mutable cache. Validation rejects unknown fields, invalid identifiers,
@@ -69,12 +82,13 @@ tracker content.
 
 ## Precedence and Compatibility
 
-Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the canonical controls receive the byte-identical established result.
+Resolution is deterministic: canonical controls win over command-local compatibility options, which win over intent defaults, which win over command defaults. Existing options such as `--fields`, `--limit`, `--token-budget`, `--format`, `--brief`, and `--full` remain accepted. Contract output marks them as hidden compatibility aliases and supplies a migration hint; traversal, cursor, side-effect, and streaming controls instead receive an explicit behavior-preservation hint because a static output control cannot replace their semantics. Callers that omit the four shaping dimensions retain the established data projection; the one intentional envelope correction is that repeated `row_contract` metadata is now opt-in.
 
 ```bash
 pm list-open --output-include id,title,status --output-limit 10
 pm context --for orient --output-budget 900 --output-format toon
 pm search "runtime contracts" --output-limit 5 --output-format json
+pm stats --output-row-contract
 pm contracts --full --json
 ```
 
@@ -93,6 +107,7 @@ const result = await pm.list({
   outputInclude: "id,title,status",
   outputLimit: 10,
   outputBudget: 800,
+  outputRowContract: true,
   outputSession: {
     version: 1,
     id: "orientation",