@unbrained/pm-cli 2026.8.10 → 2026.8.12

package/dist/sdk/governance/health.d.ts

@@ -15,6 +15,8 @@ export interface HealthCheck {
     name: "settings" | "directories" | "settings_values" | "telemetry" | "extensions" | "storage" | "locks" | "integrity" | "history_drift" | "vectorization";
     /** Lifecycle state reported for status. */
     status: HealthStatus;
+    /** Boolean companion to status for direct agent and assurance predicates. */
+    ok: boolean;
     /** Value that configures or reports details for this contract. */
     details: Record<string, unknown>;
 }
@@ -113,7 +115,7 @@ interface ExtensionHealthTriageSummary {
     top_warnings: string[];
     remediation: string[];
 }
-/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. */
+/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance values remain immutable diagnostic evidence: write-time resolvers reject new invalid values, while health reports the bounded aggregate without requiring truthful history to be rewritten. */
 declare function isAdvisoryHealthWarning(warning: string, requireMergeDrivers?: boolean): boolean;
 declare function warningCode(value: string): string;
 declare function normalizeExtensionNameForMatch(value: string): string;

package/dist/sdk/governance/health.js

@@ -4,7 +4,7 @@
  * Implements the pm health 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]="539b0cb4-5e20-51e2-a33e-1a43ca961f05")}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]="af3d60bd-94d4-52e8-90e3-7929ce04428c")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
@@ -54,12 +54,13 @@ const TELEMETRY_SERVER_MAX_SCHEMA_VERSION_HEADERS = [
     "x-pm-telemetry-max-schema-version",
     "x-pm-telemetry-max-version",
 ];
-/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. */
+/** Advisory warnings are surfaced for visibility but never flip overall health to not-ok. Telemetry is opt-out, non-critical observability: a queued/unreachable telemetry endpoint or corrupt local telemetry state is not a project-health failure and must not block agents that gate on `pm health` `ok`. History over-compaction-threshold warnings are likewise advisory maintenance hints — a deep stream is healthy, just a candidate for `pm history-compact`. Invalid legacy provenance values remain immutable diagnostic evidence: write-time resolvers reject new invalid values, while health reports the bounded aggregate without requiring truthful history to be rewritten. */
 function isAdvisoryHealthWarning(warning, requireMergeDrivers = false) {
     return (warning.startsWith("telemetry_") ||
         warning.startsWith("history_stream_over_compact_threshold:") ||
         warning.startsWith("stale_in_progress_items:") ||
         warning.startsWith("provenance_resolver_zero_success:") ||
+        warning.startsWith("provenance_value_domain_invalid:") ||
         (!requireMergeDrivers &&
             warning.startsWith("merge_driver_configuration_missing:")));
 }
@@ -360,6 +361,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         check: {
             name: "integrity",
             status: normalizedWarnings.length === 0 ? "ok" : "warn",
+            ok: normalizedWarnings.length === 0,
             details: {
                 checked_item_files: itemScan.paths.length,
                 checked_history_streams: historyScan.files.length,
@@ -703,6 +705,7 @@ async function buildExtensionCheck(pmRoot, settings, noExtensionsFlag) {
         check: {
             name: "extensions",
             status: extensionWarnings.length === 0 ? "ok" : "warn",
+            ok: extensionWarnings.length === 0,
             details: {
                 ...loadResult,
                 loaded: loadedSummaries,
@@ -951,6 +954,7 @@ function applyBriefHealthProjection(result) {
         checks: result.checks.map((check) => ({
             name: check.name,
             status: check.status,
+            ok: check.ok,
             details: summarizeHealthCheckDetails(check, BRIEF_HEALTH_DETAIL_LIMIT),
         })),
         warnings: warningsSummary.sample,
@@ -978,6 +982,7 @@ function applySummaryHealthProjection(result) {
             .map((check) => ({
             name: check.name,
             status: check.status,
+            ok: check.ok,
             details: {},
         })),
         warning_count: warningsSummary.count,
@@ -1261,6 +1266,7 @@ async function buildTelemetryCheck(settings, options) {
         check: {
             name: "telemetry",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 enabled: settings.telemetry.enabled,
                 capture_level: settings.telemetry.capture_level,
@@ -1306,6 +1312,7 @@ async function buildLocksCheck(pmRoot) {
             check: {
                 name: "locks",
                 status: "warn",
+                ok: false,
                 details: {
                     active_lock_count: 0,
                     stale_lock_count: 0,
@@ -1331,6 +1338,7 @@ async function buildLocksCheck(pmRoot) {
         check: {
             name: "locks",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 active_lock_count: scan.active_lock_count,
                 stale_lock_count: scan.stale_lock_count,
@@ -1354,6 +1362,7 @@ async function buildHistoryDriftCheck(pmRoot, items) {
         check: {
             name: "history_drift",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 checked_items: items.length,
                 cache_hit_verification: cacheHitVerification,
@@ -1519,6 +1528,7 @@ async function buildVectorizationCheck(pmRoot, settings, items, refreshPolicy, v
         check: {
             name: "vectorization",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 semantic_runtime_available: snapshot.semanticRuntimeAvailable,
                 compatibility_mode_auto_defaults: snapshot.runtimeDefaults.auto_ollama_defaults_applied,
@@ -1661,7 +1671,7 @@ async function readHealthItems(params) {
 }
 function buildSkippedHealthCheck(name) {
     return {
-        check: { name, status: "ok", details: { skipped: true } },
+        check: { name, status: "ok", ok: true, details: { skipped: true } },
         warnings: [],
     };
 }
@@ -1670,6 +1680,7 @@ function buildSettingsHealthCheck(settingsPath, settings, normalizedSettingsRead
         name: "settings",
         /* c8 ignore next -- settings read-warning status split is covered in broader read-settings integration tests */
         status: normalizedSettingsReadWarnings.length === 0 ? "ok" : "warn",
+        ok: normalizedSettingsReadWarnings.length === 0,
         details: {
             path: settingsPath,
             version: settings.version,
@@ -1683,6 +1694,7 @@ function buildDirectoriesHealthCheck(directoryState, strictDirectories) {
     return {
         name: "directories",
         status: directoryState.missingDirs.length === 0 ? "ok" : "warn",
+        ok: directoryState.missingDirs.length === 0,
         details: {
             required: directoryState.requiredDirs,
             optional: directoryState.optionalDirs,
@@ -1697,6 +1709,7 @@ function buildSettingsValuesHealthCheck(settingWarnings) {
     return {
         name: "settings_values",
         status: settingWarnings.length === 0 ? "ok" : "warn",
+        ok: settingWarnings.length === 0,
         details: { warnings: settingWarnings },
     };
 }
@@ -1719,6 +1732,10 @@ function buildStorageHealthCheck(items, settings, historySummary, authorAttribut
             !hasStaleInProgressItems
             ? "ok"
             : "warn",
+        ok: historySummary.over_threshold.length === 0 &&
+            historySummary.orphaned.length === 0 &&
+            !hasActionableAuthorWarnings &&
+            !hasStaleInProgressItems,
         details: {
             items: items.length,
             history_streams: historySummary.count,
@@ -1990,4 +2007,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=539b0cb4-5e20-51e2-a33e-1a43ca961f05
+//# debugId=af3d60bd-94d4-52e8-90e3-7929ce04428c

package/dist/sdk/governance/validate-item-reader.js

@@ -5,14 +5,14 @@
  * validation run.
  */
 
-!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]="896ffe11-2cf1-5de0-8d07-5585d4f30c94")}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]="01f042d0-7f02-59f5-8894-cf48eb936d99")}catch(e){}}();
 import { listAllItemMetadata, listAllItemMetadataWithBody, } from "../../core/store/item-store.js";
 /** Load collections for normal checks and add bodies only when history hashes must be verified. */
 export async function readValidateItems(params) {
     if (params.includeBody) {
-        return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
+        return listAllItemMetadataWithBody(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema, { forceSourceScan: true });
     }
     return listAllItemMetadata(params.pmRoot, params.settings.item_format, params.typeToFolder, params.warnings, params.settings.schema);
 }
 //# sourceMappingURL=validate-item-reader.js.map
-//# debugId=896ffe11-2cf1-5de0-8d07-5585d4f30c94
+//# debugId=01f042d0-7f02-59f5-8894-cf48eb936d99

package/dist/sdk/governance/validate.d.ts

@@ -75,6 +75,8 @@ export interface ValidateCheck {
     name: ValidateCheckName;
     /** Lifecycle state reported for status. */
     status: ValidateStatus;
+    /** Direct machine predicate derived from whether status is ok. */
+    ok: boolean;
     /** Value that configures or reports details for this contract. */
     details: Record<string, unknown>;
 }

package/dist/sdk/governance/validate.js

@@ -4,7 +4,7 @@
  * Implements the pm validate 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]="b5b7e497-f067-5504-9ffa-fd177997c518")}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]="5affc1f1-2b4f-5f04-a6cb-c3e389bcb356")}catch(e){}}();
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
@@ -913,6 +913,7 @@ function buildMetadataCheck(items, metadataPolicy, statusRegistry, verboseDiagno
         check: {
             name: "metadata",
             status: warningTokens.length === 0 ? "ok" : "warn",
+            ok: warningTokens.length === 0,
             details,
         },
         warnings: warningTokens,
@@ -957,6 +958,7 @@ function buildResolutionCheck(items, statusRegistry, verboseDiagnostics) {
         check: {
             name: "resolution",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 checked_closed_items: closedItems.length,
                 missing_resolution_items: missingResolutionRows.length,
@@ -1026,6 +1028,7 @@ function buildDependencyReferencesCheck(items, verboseDiagnostics, statusRegistr
         check: {
             name: "dependency_references",
             status: activeRows.length === 0 ? "ok" : "warn",
+            ok: activeRows.length === 0,
             details: {
                 checked_items: items.length,
                 dangling_reference_count: activeRows.length + legacyRows.length,
@@ -1582,6 +1585,7 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
                 : warnings.length === 0
                     ? "ok"
                     : "warn",
+            ok: !hasErrorSeverityCycle && warnings.length === 0,
             details: {
                 checked_active_items: rows.activeItems.length,
                 active_closure_like_metadata_items: rows.closureLikeRows.length,
@@ -1709,6 +1713,7 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
         check: {
             name: "files",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 workspace_root: workspaceRoot,
                 scan_mode_requested: fileCandidates.requestedMode,
@@ -1786,6 +1791,7 @@ async function buildHistoryDriftCheck(pmRoot, items, verboseDiagnostics) {
         check: {
             name: "history_drift",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 checked_items: items.length,
                 drifted_items_count: driftedItems.length,
@@ -1859,6 +1865,7 @@ function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
         check: {
             name: "command_references",
             status: warnings.length === 0 ? "ok" : "warn",
+            ok: warnings.length === 0,
             details: {
                 checked_items: items.length,
                 linked_commands_scanned: linkedCommandsScanned,
@@ -1905,6 +1912,7 @@ function buildFormatVersionCheck(items, verboseDiagnostics) {
         check: {
             name: "format_version",
             status,
+            ok: status === "ok",
             details: {
                 checked_items: items.length,
                 current_format_version: CURRENT_ITEM_FORMAT_VERSION,
@@ -2108,13 +2116,15 @@ async function buildStorageIntegrityCheck(pmRoot, items, typeToFolder, settings)
     if (pendingMergeDecisions.length > 0) {
         warnings.push(`validate_merge_decisions_unreviewed:${pendingMergeDecisions.length}`);
     }
+    const status = errorCount > 0 ? "error" : warnings.length > 0 ? "warn" : "ok";
     return {
         check: {
             name: "storage_integrity",
             // Corruption findings fail the check; fence drift alone is a warning —
             // the workspace data is intact, but future merges of uncovered paths
             // would fall back to git's default text driver.
-            status: errorCount > 0 ? "error" : warnings.length > 0 ? "warn" : "ok",
+            status,
+            ok: status === "ok",
             details: {
                 ...scan,
                 merge_fence: fenceAudit,
@@ -2346,4 +2356,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=b5b7e497-f067-5504-9ffa-fd177997c518
+//# debugId=5affc1f1-2b4f-5f04-a6cb-c3e389bcb356

package/dist/sdk/graph/durable-cache.d.ts

@@ -1,4 +1,4 @@
-import type { RelationshipAuditSnapshot } from "./governance.js";
+import { type RelationshipAuditSnapshot } from "./governance.js";
 /** Envelope format version; any change invalidates persisted entries. */
 export declare const GRAPH_DURABLE_CACHE_VERSION = 1;
 /** Workspaces below this item count skip implicit persistence. */

package/dist/sdk/graph/durable-cache.js

@@ -15,10 +15,11 @@
  * threshold or after an explicit `pm graph index --rebuild` opt-in.
  */
 
-!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]="ee260dcf-f4df-5997-a8d7-691c19c66a41")}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]="4cb399d6-7311-5e2d-a8d2-e0140530ec72")}catch(e){}}();
 import path from "node:path";
 import { readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../../core/fs/fs-utils.js";
 import { acquireLock } from "../../core/lock/lock.js";
+import { isSemanticContextKind, } from "./governance.js";
 /** Envelope format version; any change invalidates persisted entries. */
 export const GRAPH_DURABLE_CACHE_VERSION = 1;
 /** Workspaces below this item count skip implicit persistence. */
@@ -140,19 +141,75 @@ export function shouldPersistDurableGraphCache(itemCount, envelopeExists) {
 }
 /** Return whether a decoded value is a string-keyed non-negative integer count map. */
 function isNonnegativeCountRecord(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        Object.values(value).every((count) => Number.isInteger(count) && count >= 0));
+    return isRecord(value) && Object.values(value).every(isNonnegativeInteger);
+}
+/** Return whether a decoded value is a non-array record. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Return whether a decoded value is a non-negative integer. */
+function isNonnegativeInteger(value) {
+    return Number.isInteger(value) && Number(value) >= 0;
+}
+/** Return whether a decoded value is a finite share in the inclusive unit interval. */
+function isUnitShare(value) {
+    return (typeof value === "number" &&
+        Number.isFinite(value) &&
+        value >= 0 &&
+        value <= 1);
+}
+/** Apply a validator only when an optional decoded value is present. */
+function isOptionalValid(value, validate) {
+    return value === undefined || validate(value);
+}
+/** Return whether a decoded record contains finite shares in the inclusive unit interval. */
+function isUnitShareRecord(value) {
+    return isRecord(value) && Object.values(value).every(isUnitShare);
 }
 /** Return whether every decoded item-type coverage entry contains valid counts. */
 function isNonnegativeCoverageByTypeRecord(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
+    if (!isRecord(value))
         return false;
-    return Object.values(value).every((entry) => typeof entry === "object" &&
-        entry !== null &&
-        !Array.isArray(entry) &&
-        [entry.active, entry.isolated, entry.degree_leq_one].every((count) => Number.isInteger(count) && count >= 0));
+    return Object.values(value).every((entry) => isRecord(entry) &&
+        [entry.active, entry.isolated, entry.degree_leq_one].every(isNonnegativeInteger));
+}
+/** Decode and cross-check optional graph-composition fields as one coherent unit. */
+function decodeGraphComposition(edges, edgesByKind, edgeShareByKind, semanticEdgesValue, semanticEdgeShareValue) {
+    const values = [
+        edgeShareByKind,
+        semanticEdgesValue,
+        semanticEdgeShareValue,
+    ];
+    const presentCount = values.filter((value) => value !== undefined).length;
+    if (presentCount === 0) {
+        return {
+            edge_share_by_kind: {},
+            semantic_edges: 0,
+            semantic_edge_share: 0,
+        };
+    }
+    if (presentCount !== values.length ||
+        !isUnitShareRecord(edgeShareByKind) ||
+        !isNonnegativeInteger(semanticEdgesValue) ||
+        !isUnitShare(semanticEdgeShareValue)) {
+        return undefined;
+    }
+    const edgeEntries = Object.entries(edgesByKind);
+    if (edgeEntries.reduce((sum, [, count]) => sum + count, 0) !== edges ||
+        Object.keys(edgeShareByKind).length !== edgeEntries.length ||
+        edgeEntries.some(([kind, count]) => edgeShareByKind[kind] !== (edges === 0 ? 0 : count / edges))) {
+        return undefined;
+    }
+    const semanticEdges = edgeEntries.reduce((sum, [kind, count]) => sum + (isSemanticContextKind(kind) ? count : 0), 0);
+    if (semanticEdgesValue !== semanticEdges ||
+        semanticEdgeShareValue !== (edges === 0 ? 0 : semanticEdges / edges)) {
+        return undefined;
+    }
+    return {
+        edge_share_by_kind: edgeShareByKind,
+        semantic_edges: semanticEdgesValue,
+        semantic_edge_share: semanticEdgeShareValue,
+    };
 }
 /** Decode one persisted audit census baseline, undefined on any defect. */
 function decodeBaseline(raw) {
@@ -160,32 +217,44 @@ function decodeBaseline(raw) {
         return undefined;
     try {
         const parsed = JSON.parse(raw);
-        if (typeof parsed !== "object" || parsed === null)
+        if (!isRecord(parsed))
             return undefined;
         const snapshot = parsed;
         const profile = snapshot.profile;
-        if (typeof snapshot.saved_at !== "string" ||
-            typeof snapshot.fingerprint !== "string" ||
-            !isNonnegativeCountRecord(snapshot.affected_subjects_by_code) ||
-            typeof profile !== "object" ||
-            profile === null ||
-            ![
-                profile.nodes,
-                profile.edges,
-                profile.active_nodes,
-                profile.missing_nodes,
-                profile.isolated_active_nodes,
-                profile.degree_leq_one_active_nodes,
-            ].every((value) => Number.isInteger(value) && value >= 0) ||
-            !isNonnegativeCountRecord(profile.edges_by_kind) ||
-            (profile.coverage_by_type !== undefined &&
-                !isNonnegativeCoverageByTypeRecord(profile.coverage_by_type)))
+        if (typeof snapshot.saved_at !== "string")
+            return undefined;
+        if (typeof snapshot.fingerprint !== "string")
+            return undefined;
+        if (!isNonnegativeCountRecord(snapshot.affected_subjects_by_code)) {
+            return undefined;
+        }
+        if (!isRecord(profile))
+            return undefined;
+        if (![
+            profile.nodes,
+            profile.edges,
+            profile.active_nodes,
+            profile.missing_nodes,
+            profile.isolated_active_nodes,
+            profile.degree_leq_one_active_nodes,
+        ].every(isNonnegativeInteger)) {
+            return undefined;
+        }
+        if (!isNonnegativeCountRecord(profile.edges_by_kind))
+            return undefined;
+        if (!isOptionalValid(profile.coverage_by_type, isNonnegativeCoverageByTypeRecord)) {
+            return undefined;
+        }
+        const composition = decodeGraphComposition(profile.edges, profile.edges_by_kind, profile.edge_share_by_kind, profile.semantic_edges, profile.semantic_edge_share);
+        if (composition === undefined)
             return undefined;
+        const { coverage_by_type = {} } = profile;
         return {
             ...snapshot,
             profile: {
                 ...profile,
-                coverage_by_type: profile.coverage_by_type ?? {},
+                ...composition,
+                coverage_by_type,
             },
         };
     }
@@ -202,4 +271,4 @@ export async function saveGraphAuditBaseline(pmRoot, snapshot) {
     await writeFileAtomic(graphAuditBaselinePath(pmRoot), JSON.stringify(snapshot));
 }
 //# sourceMappingURL=durable-cache.js.map
-//# debugId=ee260dcf-f4df-5997-a8d7-691c19c66a41
+//# debugId=4cb399d6-7311-5e2d-a8d2-e0140530ec72

package/dist/sdk/graph/governance.d.ts

@@ -56,6 +56,12 @@ export interface RelationshipCoverageProfile {
     edge_basis: "deduplicated_directed";
     /** Deterministic per-kind edge counts. */
     edges_by_kind: Record<string, number>;
+    /** Per-kind share of all deduplicated directed edges. */
+    edge_share_by_kind: Record<string, number>;
+    /** Edges carrying discovery, provenance, incident, or verification semantics. */
+    semantic_edges: number;
+    /** Share of all edges carrying discovery, provenance, incident, or verification semantics. */
+    semantic_edge_share: number;
     /** Nodes whose lifecycle status is active (non-terminal, non-missing). */
     active_nodes: number;
     /** Materialized placeholder nodes for referenced-but-absent items. */
@@ -89,6 +95,8 @@ export interface RelationshipAuditReport {
     /** Structural coverage metrics computed during the audit. */
     profile: RelationshipCoverageProfile;
 }
+/** Return whether a relationship kind carries provenance or verification context. */
+export declare function isSemanticContextKind(kind: string): boolean;
 /**
  * Enumerate strongly connected components with more than one member (or a
  * self-loop) over an ordering-only successor digraph using an iterative Tarjan
@@ -165,6 +173,12 @@ export interface RelationshipAuditDelta {
         degree_leq_one_active_nodes: number;
         /** Signed per-kind edge-count deltas; unchanged kinds are dropped. */
         edges_by_kind: Record<string, number>;
+        /** Signed per-kind edge-share deltas; unchanged kinds are dropped. */
+        edge_share_by_kind: Record<string, number>;
+        /** Change in semantic-context edge count. */
+        semantic_edges: number;
+        /** Change in semantic-context edge share. */
+        semantic_edge_share: number;
         /** Signed per-type coverage deltas; unchanged types are dropped. */
         coverage_by_type: Record<string, RelationshipCoverageTypeProfile>;
     };

package/dist/sdk/graph/governance.js

@@ -1,8 +1,19 @@
 
-!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]="76fa19c7-a421-5026-8de8-450285987c4e")}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]="996cfe8f-1b9b-534e-9e22-ede6f76d7cac")}catch(e){}}();
 import { isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
+/** Relationship kinds that preserve why work exists or how evidence supports it. */
+const SEMANTIC_CONTEXT_KINDS = new Set([
+    "discovered_from",
+    "incident_from",
+    "supersedes",
+    "verifies",
+]);
+/** Return whether a relationship kind carries provenance or verification context. */
+export function isSemanticContextKind(kind) {
+    return SEMANTIC_CONTEXT_KINDS.has(kind);
+}
 /** Rank used to order findings by decreasing severity. */
 const SEVERITY_RANK = {
     error: 0,
@@ -332,13 +343,22 @@ function collectCoverageReport(assembly, nodeStates, exemptIsolates, isolateExem
     const findings = [];
     appendFinding(findings, isolates, maxSampleSize, "isolated_active_node", "warning", "Active work should be reachable from the graph unless explicitly declared a valid isolate.", (count) => `${count} active item(s) with no relationships`, "Link the item to its parent, prerequisite, or origin — or register it as an exempt isolate.");
     appendFinding(findings, sparse, maxSampleSize, "sparse_active_node", "info", "Active items with a single edge often miss an honest semantic partner; sparse is not automatically defective.", (count) => `${count} active item(s) with exactly one relationship`, "Investigate for an honest second edge (story->task, defect family, cross-epic complement); do not fabricate one.");
+    const edgeCount = assembly.graph.edges().length;
+    const sortedEdgesByKind = Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right)));
+    const semanticEdges = Object.entries(sortedEdgesByKind).reduce((count, [kind, value]) => count + (isSemanticContextKind(kind) ? value : 0), 0);
     return {
         findings,
         profile: {
             nodes: assembly.graph.nodes().length,
-            edges: assembly.graph.edges().length,
+            edges: edgeCount,
             edge_basis: "deduplicated_directed",
-            edges_by_kind: Object.fromEntries(Object.entries(edgesByKind).sort(([left], [right]) => left.localeCompare(right))),
+            edges_by_kind: sortedEdgesByKind,
+            edge_share_by_kind: Object.fromEntries(Object.entries(sortedEdgesByKind).map(([kind, count]) => [
+                kind,
+                count / edgeCount,
+            ])),
+            semantic_edges: semanticEdges,
+            semantic_edge_share: edgeCount === 0 ? 0 : semanticEdges / edgeCount,
             active_nodes: tallies.active,
             missing_nodes: tallies.missing,
             isolated_active_nodes: tallies.isolated,
@@ -437,16 +457,18 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
         ]),
     ].sort();
     for (const type of typeKeys) {
-        const before = baselineCoverageByType[type];
-        const after = currentCoverageByType[type];
+        const before = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, baselineCoverageByType[type]);
+        const after = Object.assign({ active: 0, isolated: 0, degree_leq_one: 0 }, currentCoverageByType[type]);
         const delta = {
-            active: (after?.active ?? 0) - (before?.active ?? 0),
-            isolated: (after?.isolated ?? 0) - (before?.isolated ?? 0),
-            degree_leq_one: (after?.degree_leq_one ?? 0) - (before?.degree_leq_one ?? 0),
+            active: after.active - before.active,
+            isolated: after.isolated - before.isolated,
+            degree_leq_one: after.degree_leq_one - before.degree_leq_one,
         };
         if (Object.values(delta).some((value) => value !== 0))
             coverageByType[type] = delta;
     }
+    const { edge_share_by_kind: baselineEdgeShareByKind = {}, semantic_edges: baselineSemanticEdges = 0, semantic_edge_share: baselineSemanticEdgeShare = 0, } = baseline.profile;
+    const { edge_share_by_kind: currentEdgeShareByKind = {}, semantic_edges: currentSemanticEdges = 0, semantic_edge_share: currentSemanticEdgeShare = 0, } = current.profile;
     return {
         baseline_saved_at: baseline.saved_at,
         same_snapshot: baseline.fingerprint === current.fingerprint,
@@ -461,9 +483,12 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
             degree_leq_one_active_nodes: current.profile.degree_leq_one_active_nodes -
                 baseline.profile.degree_leq_one_active_nodes,
             edges_by_kind: diffCountRecords(baseline.profile.edges_by_kind, current.profile.edges_by_kind),
+            edge_share_by_kind: diffCountRecords(baselineEdgeShareByKind, currentEdgeShareByKind),
+            semantic_edges: currentSemanticEdges - baselineSemanticEdges,
+            semantic_edge_share: currentSemanticEdgeShare - baselineSemanticEdgeShare,
             coverage_by_type: coverageByType,
         },
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=76fa19c7-a421-5026-8de8-450285987c4e
+//# debugId=996cfe8f-1b9b-534e-9e22-ede6f76d7cac

package/dist/sdk/graph/run.js

@@ -11,7 +11,7 @@
  * queries in long-lived hosts are answered from the memoized snapshot.
  */
 
-!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]="ba8e7432-539e-55d3-b105-689db55d26b2")}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]="6c8bfb7a-687a-5fbb-b408-ffdbab1187a9")}catch(e){}}();
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -19,6 +19,7 @@ import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
+import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 import { listAllItemMetadataLight } from "../../core/store/item-store.js";
 import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
@@ -74,7 +75,11 @@ function normalizeIdList(raw) {
 export function parseGraphSubcommand(raw, id, target) {
     const candidate = raw.trim().toLowerCase();
     if (!GRAPH_SUBCOMMAND_VALUES.includes(candidate)) {
-        throw new PmCliError(`Invalid graph subcommand "${raw}". Use one of: ${GRAPH_SUBCOMMAND_VALUES.join(", ")}.`, EXIT_CODE.USAGE);
+        throw createUnknownSubcommandError({
+            command_path: "graph",
+            token: candidate || "<empty>",
+            allowed: GRAPH_SUBCOMMAND_VALUES,
+        });
     }
     const subcommand = candidate;
     if (ROOTED_SUBCOMMANDS.has(subcommand) && !id?.trim()) {
@@ -714,4 +719,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=ba8e7432-539e-55d3-b105-689db55d26b2
+//# debugId=6c8bfb7a-687a-5fbb-b408-ffdbab1187a9