@unbrained/pm-cli 2026.8.5 → 2026.8.7

package/dist/sdk/stats.js

@@ -4,7 +4,7 @@
  * Implements the pm stats command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e8916552-697e-565c-91e1-4829ecb584af")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a4de53c1-bb22-591f-a064-142c642a2443")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -21,6 +21,9 @@ import { nowIso } from "../core/shared/time.js";
 import { listAllItemMetadataLight, listAllItemMetadataWithBody, } from "../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
+import { recordImprovementObservation, readImprovementLedger, } from "./improvement-ledger.js";
+import { projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, } from "./history-analytics.js";
+import { parseTestRunMeasurements } from "./test/measurements.js";
 function zeroByType(itemTypes) {
     return itemTypes.reduce((acc, value) => {
         acc[value] = 0;
@@ -73,6 +76,88 @@ export const _testOnly = {
     countNonEmptyLines,
     readHistoryStreamContents,
 };
+async function recordStatsObservations(global, options) {
+    const recorded = [];
+    const observedAt = nowIso();
+    for (const measurement of parseTestRunMeasurements(options.observe, observedAt)) {
+        recorded.push(await recordImprovementObservation({
+            metric: measurement.name,
+            value: measurement.value,
+            direction: options.direction,
+            unit: measurement.unit,
+            threshold: measurement.threshold,
+            source: options.measurementSource,
+            itemId: options.measurementItem,
+            revision: options.measurementRevision,
+            observedAt,
+            author: options.author,
+            message: options.message,
+        }, global));
+    }
+    return recorded;
+}
+function requestedBreakdowns(items, options, classifier) {
+    const breakdowns = {};
+    if (options.byAssignee) {
+        breakdowns.assignee = groupItemsByDimension(items, "assignee", classifier);
+    }
+    if (options.byTag) {
+        breakdowns.tag = groupItemsByDimension(items, "tag", classifier, {
+            tagPrefix: options.tagPrefix,
+        });
+    }
+    if (options.byPriority) {
+        breakdowns.priority = groupItemsByDimension(items, "priority", classifier);
+    }
+    return breakdowns;
+}
+async function requestedHistoryAnalytics(pmRoot, items, settings, terminalStatuses, options) {
+    const historyOptions = {
+        since: options.since,
+        eventLimit: options.eventLimit,
+        minimumSample: options.minimumSample,
+    };
+    const sharedWindow = options.provenanceCoverage || options.fleetAttribution
+        ? await readHistoryAnalyticsWindow(pmRoot, historyOptions)
+        : undefined;
+    return {
+        provenanceCoverage: options.provenanceCoverage && sharedWindow
+            ? projectProvenanceCoverageAnalytics(sharedWindow, settings.agent_identity?.harness_signals, historyOptions)
+            : undefined,
+        fleetAttribution: options.fleetAttribution && sharedWindow
+            ? projectFleetAttributionAnalytics(sharedWindow, items, terminalStatuses, historyOptions)
+            : undefined,
+    };
+}
+function assembleStatsResult(totals, byType, byStatus, optional) {
+    const hasBreakdowns = Object.keys(optional.breakdowns).length > 0;
+    return {
+        totals,
+        by_type: byType,
+        by_status: byStatus,
+        ...(optional.metadataCoverage
+            ? { metadata_coverage: optional.metadataCoverage }
+            : {}),
+        ...(hasBreakdowns ? { breakdowns: optional.breakdowns } : {}),
+        ...(optional.storage ? { storage: optional.storage } : {}),
+        ...(optional.fieldUtilization
+            ? { field_utilization: optional.fieldUtilization }
+            : {}),
+        ...(optional.improvementLedger
+            ? { improvement_ledger: optional.improvementLedger }
+            : {}),
+        ...(optional.recordedObservations.length > 0
+            ? { recorded_observations: optional.recordedObservations }
+            : {}),
+        ...(optional.provenanceCoverage
+            ? { provenance_coverage: optional.provenanceCoverage }
+            : {}),
+        ...(optional.fleetAttribution
+            ? { fleet_attribution: optional.fleetAttribution }
+            : {}),
+        generated_at: nowIso(),
+    };
+}
 /** Implements run stats for the public runtime surface of this module. */
 export async function runStats(global, options = {}) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
@@ -80,6 +165,7 @@ export async function runStats(global, options = {}) {
         throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
     }
     const settings = await readSettings(pmRoot);
+    const recordedObservations = await recordStatsObservations(global, options);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     // Field utilization needs the heavy collections (notes/learnings/files/docs/
@@ -116,36 +202,33 @@ export async function runStats(global, options = {}) {
     const metadataCoverage = options.metadataCoverage
         ? computeMetadataCoverage(items, classifier)
         : undefined;
-    const breakdowns = {};
-    if (options.byAssignee) {
-        breakdowns.assignee = groupItemsByDimension(items, "assignee", classifier);
-    }
-    if (options.byTag) {
-        breakdowns.tag = groupItemsByDimension(items, "tag", classifier, {
-            tagPrefix: options.tagPrefix,
-        });
-    }
-    if (options.byPriority) {
-        breakdowns.priority = groupItemsByDimension(items, "priority", classifier);
-    }
-    const hasBreakdowns = Object.keys(breakdowns).length > 0;
+    const breakdowns = requestedBreakdowns(items, options, classifier);
     const fieldUtilization = options.fieldUtilization
         ? computeContentFieldUtilization(items)
         : undefined;
-    return {
-        totals: {
-            items: items.length,
-            history_streams: streams.length,
-            history_entries: historyEntries,
-        },
-        by_type: byType,
-        by_status: byStatus,
-        ...(metadataCoverage ? { metadata_coverage: metadataCoverage } : {}),
-        ...(hasBreakdowns ? { breakdowns } : {}),
-        ...(storage ? { storage } : {}),
-        ...(fieldUtilization ? { field_utilization: fieldUtilization } : {}),
-        generated_at: nowIso(),
-    };
+    const improvementLedger = options.measurements === true || recordedObservations.length > 0
+        ? await readImprovementLedger({
+            pmRoot,
+            metric: options.metric,
+            itemId: options.measurementItem,
+            limit: options.measurementLimit,
+        })
+        : undefined;
+    const { provenanceCoverage, fleetAttribution } = await requestedHistoryAnalytics(pmRoot, items, settings, statusRegistry.terminal_statuses, options);
+    return assembleStatsResult({
+        items: items.length,
+        history_streams: streams.length,
+        history_entries: historyEntries,
+    }, byType, byStatus, {
+        metadataCoverage,
+        breakdowns,
+        storage,
+        fieldUtilization,
+        improvementLedger,
+        recordedObservations,
+        provenanceCoverage,
+        fleetAttribution,
+    });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=e8916552-697e-565c-91e1-4829ecb584af
+//# debugId=a4de53c1-bb22-591f-a064-142c642a2443

package/docs/COMMANDS.md

@@ -82,6 +82,8 @@ pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
 pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
 pm upgrade --dry-run
 pm upgrade --packages-only
 pm upgrade --cli-only --repair
@@ -89,6 +91,13 @@ pm upgrade --cli-only --repair
 
 `pm install` and `pm package` are the preferred package-first workflow. `pm package` and `pm extension` bare invocations default to `--explore` so agents can list installed packages without remembering an action flag. `pm install '*'`, shell-expanded `pm install *`, and `pm install all` install bundled first-party packages. `pm extension` remains as a compatibility command for direct extension lifecycle operations.
 Install output includes a light `verification` summary with target tracker root, activation state, registered commands/actions/item types, and an `ok|degraded` health verdict. Runtime activation failure sets the command result and process exit status to failure; inspect `activation_diagnostics` and `command_discovery.next_steps` for the exact recovery path.
+Bare install names use bundled aliases before installed npm packages. Every
+install result reports `source_resolution`; when both candidates exist it marks
+the choice ambiguous and provides explicit bare and `npm:` retry commands.
+`package migrate` plans or applies active migration registrations and writes
+durable workspace-history receipts; a successful migration is skipped on later
+processes, while a failed migration remains retryable. `extension migrate` is
+the compatibility spelling.
 When package-owned commands are unavailable, usage guidance includes an install-ready retry (for example `pm install calendar`, `pm install search-advanced`, `pm install governance-audit`, or `pm install guide-shell`).
 
 ## Triage

package/docs/EXTENSIONS.md

@@ -1,6 +1,6 @@
 # Packages and Extensions
 
-Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon).
+Extension flags declared with `list: true` accumulate repeated long/short alias occurrences and comma-separated values into one array. Dynamic commands preserve flag-like variadic content after `--`, and package handlers can use the public `suppressHostOutput()` protocol when they already emitted streaming, binary, or pre-rendered output. Declarative blueprints are also checked for reserved item-field collisions during SDK lint/preflight and harness activation, so a package cannot pass author-time validation and then fail only when users create or update items. Local archive installation, command ownership, and MCP custom-field diagnostics are tracked by [pm-lw6acw](../.agents/pm/issues/pm-lw6acw.toon), [pm-6z0wzf](../.agents/pm/issues/pm-6z0wzf.toon), and [pm-yfdav2](../.agents/pm/issues/pm-yfdav2.toon). Transactional mutation guards, host-bound command test SDKs, and installed custom-type lifecycle parity are tracked by [pm-hx23u5](../.agents/pm/issues/pm-hx23u5.toon), [pm-wx2lr5](../.agents/pm/issues/pm-wx2lr5.toon), and [pm-scga6k](../.agents/pm/issues/pm-scga6k.toon). Durable migration application, explicit source resolution, and composable preflight ownership are covered in [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md).
 
 Packages add optional `pm` workflows without changing the core CLI. A package can ship one or more runtime extensions plus metadata such as docs and examples. Prefer the package-first commands in new docs and automation:
 
@@ -38,7 +38,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.
+`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.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.

package/docs/EXTENSION_LIFECYCLE.md

@@ -0,0 +1,46 @@
+# Extension Lifecycle Contracts
+
+Tracked by [pm-ig5cfe](../.agents/pm/issues/pm-ig5cfe.toon),
+[pm-495lkc](../.agents/pm/issues/pm-495lkc.toon), and
+[pm-miy5k6](../.agents/pm/issues/pm-miy5k6.toon).
+
+## Explicit Install-Source Identity
+
+A bare target may name both a bundled alias and an already-installed npm
+package. pm preserves the bundled-first compatibility rule but never hides the
+choice. Install results include `source_resolution` with the selected source,
+an `ambiguous` indicator, every matching candidate, and an explicit command for
+each. Use `pm install npm:<package>` to force npm identity or the reported bare
+alias command to force the bundled package. Install-all results carry the same
+receipt on every package row.
+
+## Durable Extension Migrations
+
+Active packages register schema migrations through `api.registerMigration`.
+Runtime preflight applies runnable migrations, and operators can plan or apply
+the same registrations explicitly:
+
+```bash
+pm package migrate --project --dry-run --json
+pm package migrate --project --json
+pm health --check-only --json
+```
+
+`pm extension migrate` is the compatibility spelling. The SDK exposes
+`runExtensionMigrations`, `PmClient.packageMigrate`, and the one-shot
+`packageMigrate`/`extensionMigrate` helpers. Dry-run never invokes package code
+or writes state. Apply records deterministic per-migration receipts in
+`.agents/pm/extension-migrations.json` through workspace history. Successful
+migrations become idempotent `skipped` rows in later processes. Failures retain
+their error for health diagnostics and are retried on the next apply. Project
+scope includes active project and global packages because both affect that
+workspace; `--global` restricts execution to global registrations.
+
+## Scoped Preflight Ownership
+
+`definePreflightOverride` and `api.registerPreflight` accept
+`{ commands, run }`. Command paths are normalized, disjoint registrations
+compose without warnings, and runtime invokes only the matching owner. Empty or
+omitted command ownership retains the legacy global behavior and collides with
+every other override. Activation summaries and persisted contribution
+inventories expose `preflight_ownership` for static doctor and tooling output.

package/docs/IMPROVEMENT_ANALYTICS.md

@@ -0,0 +1,103 @@
+# Improvement Ledger and History Analytics
+
+Tracker references: [pm-chahyq](../.agents/pm/features/pm-chahyq.toon), [pm-1wiugq](../.agents/pm/issues/pm-1wiugq.toon), [pm-gw6uyq](../.agents/pm/features/pm-gw6uyq.toon)
+
+`pm` treats project management as context management. Improvement observations and fleet analytics therefore remain attached to authoritative project context: observations are audited workspace state, while provenance and outcome analytics are bounded projections of immutable history.
+
+## Agent Quick Context
+
+- Record quantitative evidence with `pm stats --analytics '{...}'`; do not hand-edit `.agents/pm/improvement-ledger.json`.
+- Request ledger and history projections through the single typed `--analytics` JSON object. This keeps the agent-facing command contract bounded while the SDK and MCP retain their fully typed fields.
+- Ledger reads are newest-first and bounded; trends still use every matching retained observation.
+- Use an explicit metric direction. `lower` is the default; `target` requires a threshold and measures convergence toward it.
+- Use `provenanceCoverage` to find declared-but-inert or undeclared provenance dimensions.
+- Use `fleetAttribution` for observational comparisons only. It must never authorize, assign, route, rank, or evaluate an individual agent.
+- Bound history work with `since`, `eventLimit`, and `minimumSample`.
+
+## Audited improvement observations
+
+```bash
+pm stats \
+  --analytics "$(jq -cn --arg revision "$(git rev-parse HEAD)" '{
+    observe: ["quality.coverage.lines=100,unit=percent,threshold=100"],
+    direction: "higher",
+    measurementSource: "pnpm coverage",
+    measurementItem: "pm-example",
+    measurementRevision: $revision,
+    measurements: true
+  }')" \
+  --json
+```
+
+Each observation records a content identity, metric, finite value, direction, timestamp, revision provenance, author, and optional unit, threshold, source, and owning item. When no revision is supplied, `pm` uses Git HEAD when available and otherwise records an explicit `unversioned` marker.
+
+Retries are idempotent by revision, metric, source, and owner. Reusing that key with different numeric or metric-contract data fails with a conflict instead of silently rewriting history. A metric keeps one direction, unit, and—when target-directed—target threshold throughout its series.
+
+```bash
+pm stats --analytics '{"measurements":true,"metric":"quality.coverage.lines","measurementLimit":20}'
+```
+
+The `improvement_ledger` result contains:
+
+- `observations`: a bounded newest-first page;
+- `total` and `truncated`: the complete match count and omission state;
+- `trends`: baseline, latest, delta, improvement state, and sample count per metric;
+- `source: audited_workspace_singleton`: the state provenance receipt.
+
+The singleton is written through the workspace lock and `_workspace` hash-chained audit stream. Compaction may reduce historical patches, but it does not remove current ledger state.
+
+## Provenance coverage
+
+```bash
+pm stats --analytics '{"provenanceCoverage":true,"since":"-30d","eventLimit":10000,"minimumSample":5}' --json
+```
+
+This projection compares configured harness signal descriptors with observed immutable history. It reports descriptor coverage, observed/unavailable/legacy-missing values, inert dimensions with sufficient explicit samples, undeclared dimensions, and stable warning codes. The live corpus is the positive control; deliberately missing descriptors and unavailable values provide negative controls in tests.
+
+## Fleet attribution
+
+```bash
+pm stats --analytics '{"fleetAttribution":true,"since":"-30d","eventLimit":10000,"minimumSample":5}' --json
+```
+
+Fleet attribution groups bounded events by harness, model, and author source. Each group reports state and annotation events, terminal transitions, reopens, and issues linked with `discovered_from` to closed work. Rates remain `null` until the close denominator reaches `minimum_sample`.
+
+The result always includes `policy: observational_only_not_for_authorization_or_routing`. Missing dimensions are `unavailable`, small denominators are `insufficient`, and a `window` receipt states the lower bound, consumed event count, truncation, and continuation cursor.
+
+## SDK
+
+```ts
+import {
+  readImprovementLedger,
+  recordImprovementObservation,
+  runFleetAttributionAnalytics,
+  runProvenanceCoverageAnalytics,
+} from "@unbrained/pm-cli/sdk";
+
+await recordImprovementObservation(
+  {
+    metric: "quality.coverage.lines",
+    value: 100,
+    direction: "higher",
+    unit: "percent",
+    revision: process.env.GIT_COMMIT,
+  },
+  { path: ".agents/pm" },
+);
+
+const ledger = await readImprovementLedger({
+  pmRoot: ".agents/pm",
+  metric: "quality.coverage.lines",
+  limit: 20,
+});
+```
+
+`PmClient.stats()` exposes the combined typed contract. The lower-level functions support packages that need one primitive without constructing a command transport. MCP uses the same action schema; its direction field is named `improvementDirection` to avoid collision with dependency-graph traversal direction. The CLI deliberately folds the new analytics fields into one validated `--analytics` object so its help and contract surface stay within the enforced agent-token budget.
+
+## Safety and interpretation
+
+- Treat observations as evidence, not a universal objective function. Record the producing gate and owning item so context survives.
+- Compare like-for-like metric contracts; a changed unit, direction, or target should use a new metric name.
+- Do not infer causality from attribution. The projection describes recorded history and relationship links only.
+- A truncated window is incomplete evidence. Resume or increase the bound before publishing conclusions.
+- Keep credentials, private payloads, host identifiers, and customer data out of metric names, sources, messages, and item links.

package/docs/OUTPUT_PROJECTION_CONTRACTS.md

@@ -213,19 +213,19 @@ metadata as a continuation negative control. The checked-in report is
 
 | Intent | 2-item tokens / budget | 2,243-item tokens / budget | Current-scale rows | Degradation |
 | ------ | ---------------------- | -------------------------- | ------------------ | ----------- |
-| `context:orient` | 707 / 2,400 | 1,000 / 2,400 | 3 | bounded sections |
+| `context:orient` | 735 / 2,400 | 1,028 / 2,400 | 3 | bounded sections |
 | `get:inspect` | 401 / 3,200 | 415 / 3,200 | item envelope | standard item |
-| `list:triage` | 393 / 3,200 | 3,181 / 3,200 | 70 | budget-derived rows |
+| `list:triage` | 443 / 3,200 | 3,189 / 3,200 | 69 | budget-derived rows |
 | `next:execute` | 395 / 1,200 | 1,171 / 1,200 | 14 | budget-derived rows |
-| `search:discover` | 301 / 1,800 | 1,763 / 1,800 | 28 | budget-derived rows |
+| `search:discover` | 350 / 1,800 | 1,761 / 1,800 | 27 | budget-derived rows |
 
 Whole-answer cursor cost is measured against the unprojected single call for
 the identical ordered row set:
 
 | Family | Rows | Pages | Optimized bytes/row | Optimized walk | Repeated-metadata control | Unbounded call | Walk / unbounded |
 | ------ | ---- | ----- | ------------------- | -------------- | ------------------------- | -------------- | ---------------- |
-| `list:triage` | 1,998 | 30 | 172.29 | 344,234 B | 379,875 B | 1,558,741 B | 0.2208 |
-| `search:discover` | 1,998 | 64 | 201.24 | 402,075 B | 454,869 B | 1,681,847 B | 0.2391 |
+| `list:triage` | 1,998 | 31 | 172.93 | 345,519 B | 387,489 B | 1,558,741 B | 0.2217 |
+| `search:discover` | 1,998 | 66 | 202.50 | 404,591 B | 470,046 B | 1,681,847 B | 0.2406 |
 
 These are corpus-generated figures, not live tracker payloads. The generated
 corpus contains 2,243 items; the `status:all` query intentionally excludes 245

package/docs/README.md

@@ -53,12 +53,14 @@ pm guide release --json
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [SDK Context Coordination](SDK_CONTEXT_COORDINATION.md) - durable mutation events, bounded duplicate governance, and scale-safe package primitives.
+- [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [SDK Context Integrity Primitives](SDK_CONTEXT_INTEGRITY_PRIMITIVES.md) - batch duplicate discovery, structured errors, Plan evidence/lifecycle, sparse settings, tombstones, linked-test output, relocation diagnostics, and scoped output services.
 - [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.
 - [Packages and Extensions](EXTENSIONS.md) - package install workflows, runtime extension lifecycle, and API reference.
+- [Extension Lifecycle Contracts](EXTENSION_LIFECYCLE.md) - source identity, durable migrations, and scoped preflight ownership.
 - [Extension Author Contracts](EXTENSION_AUTHOR_CONTRACTS.md) - the stability guarantees and contract surface package authors build against.
 - [SDK](SDK.md) - public import surfaces and typed authoring examples.
 - [Multi-Branch Merge Safety](MERGE_SAFETY.md) - semantic tracker merge drivers, post-merge integrity gates, delete/modify policy, and recovery-receipt retention.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon) and [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.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), and [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon).
 
 ## Agent Quick Context
 
@@ -15,6 +15,58 @@ Every built-in read surface uses four output dimensions: what to include, how mu
 
 The contract covers `list`, `context`, `search`, `get`, `next`, `health`, `deps`, `graph`, `history`, `activity`, `validate`, `events`, `contracts`, `comments`, `notes`, `files`, `docs`, `stats`, and `aggregate`, including list aliases and `ctx`.
 
+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.
+
+## Cross-Call Context Sessions
+
+`--output-session <json>` / `outputSession` composes the four per-call
+dimensions across a request group. The caller supplies versioned state and
+passes the returned `read_session.next_state` to the next read:
+
+```json
+{
+  "version": 1,
+  "id": "orientation",
+  "token_budget": 4000,
+  "spent_tokens": 0,
+  "seen_item_ids": []
+}
+```
+
+The session ceiling and an explicit `--output-budget` both bind; the smaller
+remaining allowance wins. Rows for item facts already present in the caller's
+context become `{ "id": "pm-a1b2", "context_ref":
+"session:orientation:pm-a1b2" }` instead of repeating prose. References retain
+stable item identity and can be restored with `pm get <item-id> --brief` when
+the prior context is unavailable. The receipt reports estimated and charged
+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.
+
+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,
+unsupported schema versions, unsafe integers, and spend beyond the declared
+ceiling before a read executes.
+
+The mandatory orientation calibration runs `context`, `list`, `search`, `get`,
+and `next` against both a two-item tracker and a 2,243-item tracker. Its
+cross-call ceilings are strict: complete serialized bytes and cumulative spend
+may only shrink, while repeat suppression may only hold or improve. The gate
+also fixes the expected unique-fact shape:
+
+| Tracker tier | Group spend / budget | Seen items | Suppressed repeats | Delivered bytes |
+| ------------ | -------------------- | ---------- | ------------------ | --------------- |
+| 2 items      | 3,663 / 20,000       | 2          | 3                  | 14,646          |
+| 2,243 items  | 9,999 / 20,000       | 106        | 7                  | 39,985          |
+
+These are deterministic synthetic-corpus measurements from
+`scripts/release/context-intent-calibration.json`; they contain no hosted
+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.
@@ -41,6 +93,13 @@ const result = await pm.list({
   outputInclude: "id,title,status",
   outputLimit: 10,
   outputBudget: 800,
+  outputSession: {
+    version: 1,
+    id: "orientation",
+    token_budget: 4000,
+    spent_tokens: 0,
+    seen_item_ids: [],
+  },
 });
 ```
 

package/docs/RELEASING.md

@@ -20,7 +20,8 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon),
 [pm-4s24d2](../.agents/pm/issues/pm-4s24d2.toon),
 [pm-39cqqx](../.agents/pm/tasks/pm-39cqqx.toon), stable peer compatibility
 [pm-csuce0](../.agents/pm/issues/pm-csuce0.toon), and artifact budgets
-[pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+[pm-998juj](../.agents/pm/tasks/pm-998juj.toon), plus exact-tag recovery
+[pm-lwnifd](../.agents/pm/issues/pm-lwnifd.toon).
 
 ## Version Policy
 
@@ -232,11 +233,14 @@ git push origin v<version>
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
 
 - full-history checkout
-- manual `workflow_dispatch` by tag for recovery when an immutable npm version already exists; the reviewed current `main` source runs the gates so a historical tag cannot be blocked by an expired external fixture
+- manual `workflow_dispatch` by tag for recovery. An authenticated exact-version probe keeps already-published access recovery on the reviewed dispatch-time `main` source; when the immutable tag exists but npm publication never completed, recovery checks out that exact tagged source and retains the original version guard
 - pnpm install with frozen lockfile
 - version policy and tag guard
 - secret scan
-- build, typecheck, test, and coverage
+- build, clone-local merge-driver installation, typecheck, test, and coverage
+- generated changelog verification and `pm-changelog` installation before the
+  tracker-bearing static gate, so a clean checkout does not misclassify the
+  managed extension's linked files as missing
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
@@ -248,7 +252,10 @@ git push origin v<version>
 - `npm publish --access public --provenance --tag latest`, skipped on retry
   only when the exact version is anonymously visible from a fresh npm cache.
   If the package is public but the target version is absent, the workflow
-  publishes immediately without attempting a package-access mutation. Only
+  publishes immediately without attempting a package-access mutation. A
+  dispatch may do so only when its source-selection preflight pinned the
+  checkout to the requested immutable tag; reviewed-main recovery continues
+  to refuse publication of a missing target. Only
   when neither the target nor package metadata is anonymously visible does the
   same-tag recovery path attempt to restore public package access, because a
   hidden version can also return 404 to authenticated metadata reads. After a
@@ -272,7 +279,7 @@ git push origin v<version>
   `scripts/release/verify-installed-agent-session.mjs`. Separate npm and Bun
   install roots must contain the resolved executable, then each drives the
   cold-start `init -> context -> create -> claim -> annotate -> files -> close
-  -> validate -> get -> context` loop. The structured report identifies the
+-> validate -> get -> context` loop. The structured report identifies the
   failing step and records per-step output ceilings and estimated token cost.
 - GitHub Release creation
 - GitHub Release metadata verification through the same local verification script
@@ -312,25 +319,31 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   ordinal recovery version. Rerun `.github/workflows/release.yml` with
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
-  duplicate npm publication for an anonymously visible version and attempts
-  protected access recovery before anonymous probes. A dispatch refuses to
-  publish when that immutable version is absent; first publication remains owned
-  by the original tag-push run.
-  Authenticated metadata is not used as the existence oracle because a hidden
-  immutable version can return 404 there as well.
+  duplicate npm publication for an anonymously visible version. Before
+  installing or running gates, dispatch performs an authenticated exact-version
+  probe. An
+  existing version keeps the reviewed dispatch-time `main` source and cannot
+  be republished. A definitive missing-version response pins the checkout to
+  the existing immutable tag, reapplies the version guard, installs the managed
+  changelog extension before tracker measurement, and permits first publication
+  only from that exact tagged source. Other registry failures stop before
+  source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.
-- A manual exact-tag `workflow_dispatch` recovery reasserts public npm package
-  access before consulting anonymous registry metadata. This prevents a stale
-  public cache hit from bypassing access repair; an already-visible immutable
-  version is still verified and never republished. Recovery checks out the
+- A manual exact-tag `workflow_dispatch` recovery uses isolated anonymous
+  registry probes before any account-level access mutation. A visible package
+  with a missing target version proceeds directly to exact-tag publication, so
+  a publish-capable automation token is not required to change package access.
+  Access recovery is reserved for the ambiguous case where neither the package
+  nor target version is anonymously visible. An already-visible immutable
+  version is still verified and never republished. Recovery starts from the
   dispatch-time commit SHA and fails unless the dispatch ref is the repository
-  default branch (`main`), while `RELEASE_TAG` keeps the requested immutable
-  version as the verification target. Historical recovery validates
-  the tag shape but intentionally does not require current `package.json` to
-  equal that older version; dispatch cannot publish, so this does not weaken the
-  original tag-push version guard.
+  default branch (`main`). It remains on that reviewed source when the exact
+  npm version exists. When the version is definitively absent, it switches to
+  the resolved commit behind `RELEASE_TAG`, requires `package.json` to match the
+  tag, installs the clone-local merge driver and managed changelog extension,
+  and may publish that exact source after every gate passes.
 - Record failure evidence and remediation in the release `pm` item.
 
 ### Silent skip debugging