@unbrained/pm-cli 2026.8.11 → 2026.8.12

package/dist/sdk/stats.d.ts

@@ -1,5 +1,5 @@
 import { type ContentFieldUtilizationReport } from "../core/governance/content-fields.js";
-import { type GroupedBreakdown, type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
+import { type CoverageItem, type GroupedBreakdown, type LifecycleClassifier, type MetadataCoverageReport } from "../core/governance/metadata-coverage.js";
 import { type HistoryStorageStats } from "../core/history/history-storage-stats.js";
 import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { ItemStatus, ItemType } from "../types/index.js";
@@ -7,6 +7,8 @@ import { type ImprovementDirection, type ImprovementLedgerResult, type RecordImp
 import { type FleetAttributionAnalytics, type ProvenanceCoverageAnalytics } from "./history-analytics.js";
 /** Documents the stats command options payload exchanged by command, SDK, and package integrations. */
 export interface StatsCommandOptions {
+    /** Restore zero-count item-type and status buckets for schema-governance dashboards. */
+    includeEmpty?: boolean;
     /** Include aggregate per-stream history storage metrics (sizes, depth, oldest/newest). */
     storage?: boolean;
     /** Include metadata coverage percentages (AC, estimates, resolution, tags, parent) overall and by type. */
@@ -52,6 +54,29 @@ export interface StatsCommandOptions {
     /** Minimum close or explicit-value denominator required for rates. */
     minimumSample?: number;
 }
+/** Compact, tabular lifecycle row used by the default stats type distribution. */
+export interface StatsTypeLifecycleRow {
+    /** Item type represented by this row. */
+    type: string;
+    /** Total items of this type across every lifecycle bucket. */
+    total: number;
+    /** Items in the default open lifecycle bucket. */
+    open: number;
+    /** Items in active non-default lifecycle states. */
+    in_progress: number;
+    /** Items in blocked lifecycle states. */
+    blocked: number;
+    /** Items in draft lifecycle states. */
+    draft: number;
+    /** Items in completed lifecycle states. */
+    closed: number;
+    /** Items in canceled lifecycle states. */
+    canceled: number;
+    /** Items whose custom status is outside the recognized lifecycle buckets. */
+    other: number;
+}
+/** Screen-sized type distribution rendered as one canonical TOON table. */
+export type StatsTypeBreakdown = StatsTypeLifecycleRow[];
 /** Documents the stats result payload exchanged by command, SDK, and package integrations. */
 export interface StatsResult {
     /** Value that configures or reports totals for this contract. */
@@ -61,9 +86,11 @@ export interface StatsResult {
         history_entries: number;
     };
     /** Schema type that determines the shape and validation rules for this value. */
-    by_type: Record<ItemType, number>;
+    by_type: StatsTypeBreakdown;
     /** Item counts grouped by lifecycle status. */
-    by_status: Record<ItemStatus, number>;
+    by_status: Partial<Record<ItemStatus, number>>;
+    /** Total zero-count type and status buckets omitted from the default projection. */
+    omitted_zero_buckets: number;
     /** Present only with --metadata-coverage: per-field coverage overall and by type. */
     metadata_coverage?: MetadataCoverageReport;
     /** Present only with --by-assignee/--by-tag/--by-priority: lifecycle-bucketed group breakdowns. */
@@ -89,6 +116,11 @@ export interface StatsResult {
 }
 declare function zeroByType(itemTypes: string[]): Record<ItemType, number>;
 declare function zeroByStatus(statuses: string[]): Record<ItemStatus, number>;
+declare function projectStatsDistributions(items: readonly CoverageItem[], itemTypes: readonly string[], statuses: readonly string[], classifier: LifecycleClassifier, includeEmpty: boolean): {
+    byType: StatsTypeBreakdown;
+    byStatus: Partial<Record<ItemStatus, number>>;
+    omitted: number;
+};
 declare function countNonEmptyLines(raw: string): number;
 declare function readHistoryStreamContents(pmRoot: string): Promise<Array<{
     id: string;
@@ -100,6 +132,7 @@ export declare const _testOnly: {
     zeroByStatus: typeof zeroByStatus;
     countNonEmptyLines: typeof countNonEmptyLines;
     readHistoryStreamContents: typeof readHistoryStreamContents;
+    projectStatsDistributions: typeof projectStatsDistributions;
 };
 /** Implements run stats for the public runtime surface of this module. */
 export declare function runStats(global: GlobalOptions, options?: StatsCommandOptions): Promise<StatsResult>;

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]="a4de53c1-bb22-591f-a064-142c642a2443")}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]="d28c7ac7-9801-5b0c-84c9-51deede398be")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -36,6 +36,53 @@ function zeroByStatus(statuses) {
         return acc;
     }, {});
 }
+function projectStatsDistributions(items, itemTypes, statuses, classifier, includeEmpty) {
+    const grouped = groupItemsByDimension(items, "type", classifier);
+    const presentTypes = new Set(grouped.rows.map((row) => row.key));
+    const missingTypes = itemTypes.filter((type) => !presentTypes.has(type));
+    const groupedRows = includeEmpty
+        ? [
+            ...grouped.rows,
+            ...missingTypes.map((type) => ({
+                label: type,
+                key: type,
+                total: 0,
+                buckets: {
+                    open: 0,
+                    in_progress: 0,
+                    blocked: 0,
+                    draft: 0,
+                    closed: 0,
+                    canceled: 0,
+                    other: 0,
+                },
+            })),
+        ]
+        : grouped.rows;
+    const byType = groupedRows.map((row) => ({
+        type: row.key ?? row.label,
+        total: row.total,
+        open: row.buckets.open,
+        in_progress: row.buckets.in_progress,
+        blocked: row.buckets.blocked,
+        draft: row.buckets.draft,
+        closed: row.buckets.closed,
+        canceled: row.buckets.canceled,
+        other: row.buckets.other,
+    }));
+    const counts = zeroByStatus([...statuses]);
+    for (const item of items)
+        counts[item.status] += 1;
+    const byStatus = Object.fromEntries(Object.entries(counts).filter(([, count]) => includeEmpty || count > 0));
+    return {
+        byType,
+        byStatus,
+        omitted: includeEmpty
+            ? 0
+            : missingTypes.length +
+                Object.values(counts).filter((count) => count === 0).length,
+    };
+}
 function countNonEmptyLines(raw) {
     if (raw.trim().length === 0) {
         return 0;
@@ -75,6 +122,7 @@ export const _testOnly = {
     zeroByStatus,
     countNonEmptyLines,
     readHistoryStreamContents,
+    projectStatsDistributions,
 };
 async function recordStatsObservations(global, options) {
     const recorded = [];
@@ -129,12 +177,13 @@ async function requestedHistoryAnalytics(pmRoot, items, settings, terminalStatus
             : undefined,
     };
 }
-function assembleStatsResult(totals, byType, byStatus, optional) {
+function assembleStatsResult(totals, byType, byStatus, omittedZeroBuckets, optional) {
     const hasBreakdowns = Object.keys(optional.breakdowns).length > 0;
     return {
         totals,
         by_type: byType,
         by_status: byStatus,
+        omitted_zero_buckets: omittedZeroBuckets,
         ...(optional.metadataCoverage
             ? { metadata_coverage: optional.metadataCoverage }
             : {}),
@@ -180,16 +229,8 @@ export async function runStats(global, options = {}) {
         itemIds: items.map((item) => item.id),
         commandLabel: "stats",
     });
-    const byType = zeroByType(typeRegistry.types);
-    const byStatus = zeroByStatus(statusRegistry.definitions.map((definition) => definition.id));
-    // zeroByType/zeroByStatus pre-seed a bucket for every registry type/status, and
-    // the light item-metadata reader drops any item whose type/status falls outside
-    // the active registry (parse rejects them) — so every item's bucket is already
-    // present here and no on-the-fly initialization is reachable.
-    for (const item of items) {
-        byType[item.type] += 1;
-        byStatus[item.status] += 1;
-    }
+    const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
+    const distributions = projectStatsDistributions(items, typeRegistry.types, statusRegistry.definitions.map((definition) => definition.id), classifier, options.includeEmpty === true);
     const streams = await readHistoryStreamContents(pmRoot);
     let historyEntries = 0;
     for (const stream of streams) {
@@ -198,7 +239,6 @@ export async function runStats(global, options = {}) {
     const storage = options.storage
         ? computeHistoryStorageStats(streams)
         : undefined;
-    const classifier = lifecycleClassifierFromStatusRegistry(statusRegistry);
     const metadataCoverage = options.metadataCoverage
         ? computeMetadataCoverage(items, classifier)
         : undefined;
@@ -219,7 +259,7 @@ export async function runStats(global, options = {}) {
         items: items.length,
         history_streams: streams.length,
         history_entries: historyEntries,
-    }, byType, byStatus, {
+    }, distributions.byType, distributions.byStatus, distributions.omitted, {
         metadataCoverage,
         breakdowns,
         storage,
@@ -231,4 +271,4 @@ export async function runStats(global, options = {}) {
     });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=a4de53c1-bb22-591f-a064-142c642a2443
+//# debugId=d28c7ac7-9801-5b0c-84c9-51deede398be

package/dist/sdk/test/execution.d.ts

@@ -35,6 +35,8 @@ export interface TestCommandOptions {
     addJson?: string[];
     /** Value that configures or reports remove for this contract. */
     remove?: string[];
+    /** Remove linked tests by their stable 1-based list position. */
+    removeIndex?: Array<string | number>;
     /** Value that configures or reports list for this contract. */
     list?: boolean;
     /** Value that configures or reports run for this contract. */
@@ -146,6 +148,8 @@ export interface TestResult {
     changed: boolean;
     /** Value that configures or reports count for this contract. */
     count: number;
+    /** Number of linked-test entries removed by this mutation. */
+    removed?: number;
     /** Measurements supplied for the current producing run. */
     measurements?: TestRunMeasurement[];
     /** Existing and current measurements below the selected threshold. */

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * Implements the pm test 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]="2c0646bf-44d7-521f-aea1-b0683d88a8fa")}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]="b40f54be-2d3e-5b98-9d49-cb8608a782f5")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -507,7 +507,6 @@ function parseAddJsonEntries(raw) {
         return parsed;
     });
 }
-/* c8 ignore stop */
 function parseRemoveEntries(raw) {
     if (!raw)
         return [];
@@ -516,19 +515,48 @@ function parseRemoveEntries(raw) {
         if (!trimmed) {
             throw new PmCliError("--remove requires command or path value", EXIT_CODE.USAGE);
         }
-        if (trimmed.includes("=") ||
-            /^(?:[-*+]\s+)?(?:path|command)\s*[:=]/i.test(trimmed) ||
+        const identityPrefix = /^(command|path)\s*=/i.exec(trimmed);
+        if (identityPrefix) {
+            const value = trimmed.slice(identityPrefix[0].length).trim();
+            if (!value) {
+                throw new PmCliError("--remove requires a non-empty command=<value> or path=<value>", EXIT_CODE.USAGE);
+            }
+            return {
+                kind: identityPrefix[1].toLowerCase(),
+                value,
+            };
+        }
+        if (/^[A-Za-z_][\w-]*=\S+$/u.test(trimmed)) {
+            throw new PmCliError("--remove structured selectors require command=<value> or path=<value>", EXIT_CODE.USAGE);
+        }
+        if (/^(?:[-*+]\s+)?(?:path|command)\s*:/i.test(trimmed) ||
             trimmed.startsWith("```")) {
             const kv = parseCsvKv(trimmed, "--remove");
+            const kind = kv.path !== undefined ? "path" : "command";
             const value = kv.path ?? kv.command;
             if (!value?.trim()) {
                 throw new PmCliError("--remove requires command=<value> and/or path=<value>", EXIT_CODE.USAGE);
             }
-            return value.trim();
+            return { kind, value: value.trim() };
         }
-        return trimmed;
+        return { kind: "either", value: trimmed };
     });
 }
+function parseRemoveIndexes(raw) {
+    if (!raw)
+        return [];
+    return [
+        ...new Set(raw.map((value) => {
+            const parsed = typeof value === "number" ? value : Number.parseInt(value, 10);
+            if (!Number.isInteger(parsed) ||
+                parsed < 1 ||
+                String(parsed) !== String(value).trim()) {
+                throw new PmCliError("--remove-index must be a positive integer", EXIT_CODE.USAGE);
+            }
+            return parsed;
+        })),
+    ];
+}
 function closeLinkedTestStdin(child) {
     // Force EOF on child stdin so non-interactive runs do not wait on input.
     try {
@@ -1383,7 +1411,10 @@ function resolveLinkedTestPreflightResult(params) {
 }
 function buildLinkedTestExecutionEnv(params) {
     const effectiveDirectives = resolveEffectiveLinkedTestDirectives(params.runtimeDirectives, params.linkedTest);
-    const executionEnv = { ...process.env };
+    const executionEnv = {
+        ...process.env,
+        SENTRY_ENVIRONMENT: "test",
+    };
     applyEnvDirectiveStage(executionEnv, params.runtimeDirectives);
     applyEnvDirectiveStage(executionEnv, {
         env_set: params.linkedTest.env_set ?? {},
@@ -1538,6 +1569,7 @@ async function readLinkedTestItem(params) {
         tests: loaded.document.metadata.tests ?? [],
         testRuns: loaded.document.metadata.test_runs ?? [],
         changed: false,
+        removed: 0,
     };
 }
 function linkedTestsHaveSameIdentity(left, right) {
@@ -1555,15 +1587,26 @@ function appendMissingLinkedTests(current, additions) {
     }
     return next;
 }
-function removeLinkedTestsBySelector(current, removals) {
-    if (removals.length === 0) {
-        return current;
+function removeLinkedTestsBySelector(current, removals, removeIndexes) {
+    if (removals.length === 0 && removeIndexes.length === 0) {
+        return { tests: current, removed: 0 };
     }
-    return current.filter((entry) => !removals.includes(entry.path ?? "") &&
-        !removals.includes(entry.command ?? ""));
+    const indexSet = new Set(removeIndexes);
+    const tests = current.filter((entry, index) => {
+        if (indexSet.has(index + 1))
+            return false;
+        return !removals.some((selector) => {
+            if (selector.kind === "command")
+                return entry.command === selector.value;
+            if (selector.kind === "path")
+                return entry.path === selector.value;
+            return entry.command === selector.value || entry.path === selector.value;
+        });
+    });
+    return { tests, removed: current.length - tests.length };
 }
-function applyLinkedTestMutations(previous, adds, removes) {
-    return removeLinkedTestsBySelector(appendMissingLinkedTests(previous, adds), removes);
+function applyLinkedTestMutations(previous, adds, removes, removeIndexes) {
+    return removeLinkedTestsBySelector(appendMissingLinkedTests(previous, adds), removes, removeIndexes);
 }
 function hasTestRuntimeDirectiveFlags(options) {
     return ((options.envSet?.length ?? 0) > 0 ||
@@ -1590,25 +1633,43 @@ function assertTestRunFlagUsage(options) {
     }
 }
 async function resolveLinkedTestItem(params) {
-    const { id, options, pmRoot, settings, typeToFolder, adds, removes } = params;
-    if (adds.length === 0 && removes.length === 0) {
+    const { id, options, pmRoot, settings, typeToFolder, adds, removes, removeIndexes, } = params;
+    if (adds.length === 0 && removes.length === 0 && removeIndexes.length === 0) {
         return readLinkedTestItem({ id, pmRoot, settings, typeToFolder });
     }
+    let removed = 0;
     const result = await mutateItem({
         pmRoot,
         settings,
         id,
-        op: "tests_add",
+        op: adds.length > 0 ? "tests_add" : "tests_remove",
         author: resolveAuthor(options.author, settings.author_default),
         message: options.message,
         force: options.force,
         skipNoop: true,
         mutate(document) {
             const previous = document.metadata.tests ?? [];
-            const next = applyLinkedTestMutations(previous, adds, removes);
-            document.metadata.tests = next;
+            const mutation = applyLinkedTestMutations(previous, adds, removes, removeIndexes);
+            removed = mutation.removed;
+            if ((removes.length > 0 || removeIndexes.length > 0) && removed === 0) {
+                throw new PmCliError("No linked tests matched the requested removal selector", EXIT_CODE.NOT_FOUND, {
+                    code: "linked_test_remove_no_match",
+                    unmatched: [
+                        ...removes.map((entry) => `${entry.kind}=${entry.value}`),
+                        ...removeIndexes.map((index) => `index=${index}`),
+                    ],
+                    required: "List linked tests and retry with an exact command/path or a current 1-based --remove-index.",
+                    examples: [
+                        `pm test ${id} --list`,
+                        `pm test ${id} --remove-index 1`,
+                    ],
+                });
+            }
+            document.metadata.tests = mutation.tests;
             return {
-                changedFields: stableValueEquals(previous, next) ? [] : ["tests"],
+                changedFields: stableValueEquals(previous, mutation.tests)
+                    ? []
+                    : ["tests"],
             };
         },
     });
@@ -1617,6 +1678,7 @@ async function resolveLinkedTestItem(params) {
         tests: result.item.tests ?? [],
         testRuns: result.item.test_runs ?? [],
         changed: result.changedFields.length > 0,
+        removed,
     };
 }
 function resolveTestRunOptions(options, tests) {
@@ -1780,6 +1842,7 @@ export async function runTest(id, options, global) {
         ...parseAddJsonEntries(resolvedAddJsons),
     ];
     const removes = parseRemoveEntries(resolvedRemoves);
+    const removeIndexes = parseRemoveIndexes(options.removeIndex);
     const item = await resolveLinkedTestItem({
         id,
         options,
@@ -1788,6 +1851,7 @@ export async function runTest(id, options, global) {
         typeToFolder: typeRegistry.type_to_folder,
         adds,
         removes,
+        removeIndexes,
     });
     const runOptions = resolveTestRunOptions(options, item.tests);
     const runStartedAt = options.run === true ? nowIso() : undefined;
@@ -1835,6 +1899,7 @@ export async function runTest(id, options, global) {
         warnings: warnings.length > 0 ? warnings : undefined,
         changed: item.changed,
         count: item.tests.length,
+        ...(item.removed > 0 ? { removed: item.removed } : {}),
         ...measurementProjection,
     };
 }
@@ -1874,4 +1939,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=2c0646bf-44d7-521f-aea1-b0683d88a8fa
+//# debugId=b40f54be-2d3e-5b98-9d49-cb8608a782f5

package/dist/types.d.ts

@@ -776,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]="605cf12e-6106-563a-abc0-38d648d4aa43")}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=605cf12e-6106-563a-abc0-38d648d4aa43
+//# debugId=8b39bc01-0325-5dc6-8492-585c98608076

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-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,22 @@ 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.
 
+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`
@@ -117,10 +119,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

@@ -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`.