@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/traceability/source-traceability.js

@@ -0,0 +1,293 @@
+/**
+ * @module sdk/source-traceability
+ *
+ * Composes linked-file evidence, bounded Git line attribution, item rationale,
+ * and typed relationship paths into an explainable source-to-work projection.
+ */
+
+!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]="b8b3f729-be32-5a77-b08f-f616ee068e0f")}catch(e){}}();
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { assembleWorkspaceRelationshipGraph } from "../graph/assembly.js";
+function runGit(workspaceRoot, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", [...args], {
+            cwd: workspaceRoot,
+            encoding: "utf8",
+            maxBuffer: 4 * 1024 * 1024,
+        }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve(stdout);
+        });
+    });
+}
+function validateLineRange(range) {
+    if (range &&
+        (!Number.isSafeInteger(range.start) ||
+            !Number.isSafeInteger(range.end) ||
+            range.start < 1 ||
+            range.end < range.start)) {
+        throw new RangeError("Source line range must be inclusive positive integers with end >= start.");
+    }
+}
+/** Parse an inclusive `start:end` source-line selector. */
+export function parseSourceLineRange(value) {
+    const match = /^(\d+):(\d+)$/u.exec(value.trim());
+    const range = match
+        ? { start: Number(match[1]), end: Number(match[2]) }
+        : undefined;
+    validateLineRange(range);
+    if (!range) {
+        throw new RangeError("Source line range must use start:end.");
+    }
+    return range;
+}
+function parseBlameCommits(output) {
+    const lines = new Map();
+    for (const row of output.split("\n")) {
+        const commit = /^([0-9a-f^]{40,64}) \d+ \d+(?: \d+)?$/u.exec(row)?.[1];
+        if (commit)
+            lines.set(commit, (lines.get(commit) ?? 0) + 1);
+    }
+    return lines;
+}
+function parseCommitItemReferences(output) {
+    const fields = output.split("\0");
+    const references = new Map();
+    for (let index = 0; index + 1 < fields.length; index += 2) {
+        const commit = fields[index]?.trim();
+        if (!commit)
+            continue;
+        const ids = [
+            ...new Set(fields[index + 1]?.match(/\bpm-[a-z0-9][a-z0-9-]{2,63}\b/gu) ?? []),
+        ].sort((left, right) => left.localeCompare(right));
+        references.set(commit, ids);
+    }
+    return references;
+}
+async function readGitAttribution(params) {
+    const relativePath = path.relative(params.workspaceRoot, path.resolve(params.workspaceRoot, params.sourcePath));
+    const blame = await runGit(params.workspaceRoot, [
+        "blame",
+        "--line-porcelain",
+        "-L",
+        `${params.lineRange.start},${params.lineRange.end}`,
+        "--",
+        relativePath,
+    ]);
+    const log = await runGit(params.workspaceRoot, [
+        "log",
+        "-n",
+        "256",
+        "--format=%H%x00%B%x00",
+        "--",
+        relativePath,
+    ]);
+    return {
+        commitLines: parseBlameCommits(blame),
+        commitItems: parseCommitItemReferences(log),
+        available: true,
+    };
+}
+function expandDecisionPath(params) {
+    const tail = params.current.nodes.at(-1);
+    const nextDepth = params.current.kinds.length + 1;
+    let foundDepth;
+    for (const edge of params.graph.incidentEdges(tail)) {
+        const outgoing = edge.source === tail;
+        const next = outgoing ? edge.target : edge.source;
+        if ((params.visitedDepth.get(next) ?? Number.POSITIVE_INFINITY) < nextDepth)
+            continue;
+        params.visitedDepth.set(next, nextDepth);
+        const definition = params.graph.registry().require(edge.kind);
+        const nextPath = {
+            nodes: [...params.current.nodes, next],
+            kinds: [
+                ...params.current.kinds,
+                outgoing ? edge.kind : (definition.inverse ?? edge.kind),
+            ],
+        };
+        if (params.details.get(next)?.type?.toLowerCase() === "decision") {
+            foundDepth = nextDepth;
+            params.found.push(nextPath);
+        }
+        else {
+            params.queue.push(nextPath);
+        }
+    }
+    return foundDepth;
+}
+function collectDecisionPaths(params) {
+    const queue = [
+        { nodes: [params.itemId], kinds: [] },
+    ];
+    const visitedDepth = new Map([[params.itemId, 0]]);
+    const found = [];
+    let foundDepth;
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = current.kinds.length;
+        if (foundDepth !== undefined && depth >= foundDepth)
+            continue;
+        if (depth >= params.maxDepth)
+            continue;
+        foundDepth =
+            expandDecisionPath({
+                current,
+                graph: params.graph,
+                details: params.details,
+                visitedDepth,
+                queue,
+                found,
+            }) ?? foundDepth;
+    }
+    found.sort((left, right) => left.nodes.join("\0").localeCompare(right.nodes.join("\0")));
+    return found;
+}
+function shortestDecisionPath(itemId, corpus, maxDepth) {
+    const assembly = assembleWorkspaceRelationshipGraph(corpus);
+    if (!assembly.graph.hasNode(itemId)) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const found = collectDecisionPaths({
+        itemId,
+        maxDepth,
+        graph: assembly.graph,
+        details: new Map(assembly.details.map((detail) => [detail.id, detail])),
+    });
+    const selected = found[0];
+    if (!selected) {
+        return {
+            status: "not_found",
+            nodes: [],
+            kinds: [],
+            alternative_decision_ids: [],
+        };
+    }
+    const decisionIds = [...new Set(found.map((entry) => entry.nodes.at(-1)))];
+    return {
+        status: decisionIds.length === 1 ? "found" : "ambiguous",
+        nodes: selected.nodes,
+        kinds: selected.kinds,
+        alternative_decision_ids: decisionIds.slice(1),
+    };
+}
+async function resolveGitAttribution(params) {
+    if (!params.lineRange) {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: true,
+        };
+    }
+    try {
+        return await readGitAttribution({
+            workspaceRoot: params.workspaceRoot,
+            sourcePath: params.paths[0],
+            lineRange: params.lineRange,
+        });
+    }
+    catch {
+        return {
+            commitLines: new Map(),
+            commitItems: new Map(),
+            available: false,
+        };
+    }
+}
+function sourceAmbiguities(params) {
+    const ambiguities = [];
+    if (params.hasLineRange && !params.attributionAvailable) {
+        ambiguities.push("git_attribution_unavailable");
+    }
+    if (params.hasLineRange && params.contributionLines === 0) {
+        ambiguities.push("line_attribution_unmapped");
+    }
+    if (params.decisionStatus === "ambiguous") {
+        ambiguities.push("multiple_governing_decisions");
+    }
+    if (params.decisionStatus === "not_found") {
+        ambiguities.push("governing_decision_not_found");
+    }
+    return ambiguities;
+}
+function mappedBlamedCommits(attribution) {
+    return [...attribution.commitLines.keys()].filter((commit) => (attribution.commitItems.get(commit)?.length ?? 0) > 0);
+}
+/** Enrich reverse linked-file candidates with bounded source rationale. */
+export async function explainSourceTraceability(params) {
+    validateLineRange(params.lineRange);
+    const decisionDepth = params.decisionDepth ?? 8;
+    if (!Number.isSafeInteger(decisionDepth) ||
+        decisionDepth < 1 ||
+        decisionDepth > 32) {
+        throw new RangeError("Decision path depth must be an integer from 1 to 32.");
+    }
+    const attribution = await resolveGitAttribution(params);
+    const mappedCommits = mappedBlamedCommits(attribution);
+    const explanations = new Map();
+    for (const candidate of params.candidates) {
+        const attributedCommits = [...attribution.commitLines.entries()].filter(([commit]) => attribution.commitItems.get(commit)?.includes(candidate.item.id));
+        const contributionLines = attributedCommits.reduce((total, [, lines]) => total + lines, 0);
+        const decisionPath = shortestDecisionPath(candidate.item.id, params.corpus, decisionDepth);
+        const ambiguities = sourceAmbiguities({
+            hasLineRange: params.lineRange !== undefined,
+            attributionAvailable: attribution.available,
+            contributionLines,
+            decisionStatus: decisionPath.status,
+        });
+        explanations.set(candidate.item.id, {
+            score: contributionLines * 100 +
+                candidate.files.length * 10 +
+                Math.max(0, 9 -
+                    Math.floor((Date.now() - Date.parse(candidate.item.updated_at)) /
+                        (30 * 24 * 60 * 60 * 1000))),
+            contribution_lines: contributionLines,
+            evidence: [
+                ...candidate.files.map((file) => ({
+                    kind: "linked_file",
+                    reference: file.path,
+                })),
+                ...attributedCommits.map(([commit, lines]) => ({
+                    kind: "git_commit",
+                    reference: commit.slice(0, 12),
+                    contribution_lines: lines,
+                })),
+            ],
+            rationale: {
+                value: candidate.item.value?.trim() || null,
+                why_now: candidate.item.why_now?.trim() || null,
+                outcome: candidate.item.outcome?.trim() || null,
+                objective: candidate.item.objective?.trim() || null,
+            },
+            decision_path: decisionPath,
+            ambiguities,
+        });
+    }
+    return {
+        explanations,
+        receipt: {
+            line_range: params.lineRange ?? null,
+            blamed_commit_count: attribution.commitLines.size,
+            mapped_commit_count: mappedCommits.length,
+            unmapped_commit_count: attribution.commitLines.size - mappedCommits.length,
+            decision_depth: decisionDepth,
+        },
+    };
+}
+/** Internal parser and traversal seams for deterministic boundary tests. */
+export const _testOnlySourceTraceability = {
+    mappedBlamedCommits,
+    parseBlameCommits,
+    parseCommitItemReferences,
+    shortestDecisionPath,
+};
+//# sourceMappingURL=source-traceability.js.map
+//# debugId=b8b3f729-be32-5a77-b08f-f616ee068e0f

package/dist/types.d.ts

@@ -743,7 +743,7 @@ export interface HistoryEntry {
     /** Observed agent model identifier, retained in local history. */
     agent_model?: string;
     /** Bounded signal class that supplied `agent_model`. */
-    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+    agent_model_source?: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
     /** Privacy-safe fingerprint distinguishing concurrent harness invocations. */
     agent_instance?: string;
     /** Extensible local-only descriptive agent provenance; null means declared but unavailable. */
@@ -751,7 +751,13 @@ export interface HistoryEntry {
         /** Bounded descriptive value observed for this dimension. */
         value: string;
         /** Bounded signal class that supplied the value. */
-        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+        source: "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
+        /** Confidence attached to a semantic inference. */
+        confidence?: "high" | "medium" | "low";
+        /** Versioned semantic inference rule. */
+        rule_version?: "v2";
+        /** Bounded item and lineage references supporting the inference. */
+        evidence?: readonly string[];
     } | null>>;
     /** Stable declared episode identity; absent on legacy or undeclared events. */
     agent_episode?: {
@@ -770,6 +776,8 @@ export interface HistoryEntry {
     before_hash: string;
     /** Value that configures or reports after hash for this contract. */
     after_hash: string;
+    /** Version of the item canonicalization used by before_hash and after_hash. Absent on legacy streams. */
+    item_hash_version?: number;
     /** Human-readable explanation suitable for logs and agent-facing output. */
     message?: string;
     /** Structured audit metadata that does not alter replayed item state. */

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="2a2072c1-f4a7-579e-ac11-4c75758d76d3")}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]="8b39bc01-0325-5dc6-8492-585c98608076")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -241,4 +241,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=2a2072c1-f4a7-579e-ac11-4c75758d76d3
+//# debugId=8b39bc01-0325-5dc6-8492-585c98608076

package/docs/ASSURANCE.md

@@ -0,0 +1,137 @@
+# 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), [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
+
+Assurance turns project policy into three reusable SDK-owned declarations:
+
+1. A **measurement** selects authoritative project data and produces a number or labelled set plus population, contributor, and compute-cost receipts.
+2. An **assertion** applies exactly one explicit bound, scope, lifetime, and enforcement level to a measurement. Required negative controls prove that the bound can both pass and fail.
+3. A **gate** evaluates named assertions at declared lifecycle triggers and returns one structured verdict shared by CLI, SDK, MCP, and CI callers.
+
+Declarations live in `.agents/pm/assurance.json`. Every registry mutation and non-dry gate verdict is appended through the verified workspace history stream; never edit either file directly.
+
+## Why Assurance Exists
+
+Project management is context management. A useful quality gate therefore needs more than a shell exit code: it must preserve what was measured, which population was judged, why a bound exists, who owns it, what changed the result, how expensive the evaluation was, and which immutable tree received the verdict.
+
+The assurance SDK keeps those semantics independent from presentation. Commander and MCP only normalize inputs. Package authors and CI hosts can use the same public functions without reconstructing policy in scripts.
+
+## Declaration Vocabulary
+
+Measurements support these built-in sources:
+
+| 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.
+
+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`
+- `monotone_nondecreasing` or `monotone_nonincreasing`
+- `subset_of` for labelled sets
+
+Scopes are `all`, `active`, or `filter`. A filter names another measurement whose contributors define the item population. `lifetime: hold` keeps the guarantee after its owner item becomes terminal. `lifetime: retire` retires it only after owner termination and requires `retire_reason`.
+
+Enforcement is `block`, `warn`, or `observe`. Weakening a bound, scope, lifetime, owner, source measurement, or enforcement requires `authorization_decision` naming a terminal Decision item verified by the host. The transport verifies only that explicitly named item; it never treats unrelated workspace Decisions as authorization. Tightening does not require authorization.
+
+## CLI Workflow
+
+Create a measurement:
+
+```bash
+pm assurance put measurement active-issues \
+  --definition '{"id":"active-issues","source":{"kind":"items","statuses":["open","in_progress"],"types":["Issue"]},"max_cost":5000}' \
+  --message "Track the active issue population"
+```
+
+Create an assertion with executable negative controls:
+
+```bash
+pm assurance put assertion active-issues-ceiling \
+  --definition '{"id":"active-issues-ceiling","measurement_id":"active-issues","owner_item_id":"pm-example","scope":{"kind":"active"},"ceiling":25,"lifetime":"hold","enforcement":"block","negative_control":{"cases":[{"observed":25,"expected":"pass"},{"observed":26,"expected":"fail"}]}}'
+```
+
+Create and evaluate a gate:
+
+```bash
+pm assurance put gate release-readiness \
+  --definition '{"id":"release-readiness","assertion_ids":["active-issues-ceiling"],"triggers":["ci","pre-release"]}'
+
+pm assurance run release-readiness --trigger ci --dry-run --json
+pm assurance run release-readiness --trigger pre-release --tree "$(git rev-parse HEAD)" --json
+pm assurance verdicts release-readiness --limit 20 --json
+```
+
+Registry reads and removals use the same nouns:
+
+```bash
+pm assurance list measurement --json
+pm assurance show assertion active-issues-ceiling --json
+pm assurance remove gate release-readiness
+```
+
+Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
+
+## SDK and MCP
+
+The reusable client exposes the same action grammar:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: ".agents/pm" });
+
+await pm.assurance({
+  action: "run",
+  id: "release-readiness",
+  trigger: "ci",
+  dry_run: true,
+});
+```
+
+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.
+
+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:
+
+```bash
+pm contracts --action assurance --schema-only --json
+pm contracts --command assurance --flags-only --json
+```
+
+## Verdict Contract
+
+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.
+- Prefer saved measurements and derived arithmetic over duplicating queries in scripts.
+- Give expensive graph, health, validate, or provider measurements explicit cost ceilings.
+- Keep owner items and authorization Decisions linked into the project graph.
+- Treat negative controls as part of the policy, not test decoration.
+- Use `hold` unless a time-bounded guarantee has an explicit retirement rationale.
+- Use `--dry-run` while authoring or tightening a gate, then persist a verdict against an immutable tree.

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

@@ -183,6 +183,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/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: