@unbrained/pm-cli 2026.8.21 → 2026.8.23

package/dist/sdk/governance/hierarchy-validation.js

@@ -0,0 +1,109 @@
+/**
+ * @module sdk/governance/hierarchy-validation
+ *
+ * Adapts the shared hierarchy analyzer to validation-specific diagnostics and
+ * deterministic cycle paths without coupling the analyzer to CLI policy.
+ */
+
+!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]="77a3c404-bbcd-5a5e-80bf-cb61c45af55d")}catch(e){}}();
+import { statusIsTerminal, } from "../../core/schema/runtime-schema.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { analyzeHierarchyIntegrity } from "../graph/hierarchy-integrity.js";
+/** Resolve one deterministic closed walk through a known cycle component. */
+/* c8 ignore start -- fallback branches are covered by lifecycle graph integration tests */
+export function resolveLifecycleDependencyCycleSamplePath(component, graph) {
+    const start = component[0];
+    if (component.length === 1)
+        return [start, start];
+    const componentSet = new Set(component);
+    const path = [start];
+    const visited = new Set([start]);
+    const search = (current) => {
+        for (const next of (graph.get(current) ?? []).filter((candidate) => componentSet.has(candidate))) {
+            if (next === start && path.length > 1) {
+                path.push(start);
+                return true;
+            }
+            if (visited.has(next))
+                continue;
+            visited.add(next);
+            path.push(next);
+            if (search(next))
+                return true;
+            path.pop();
+            visited.delete(next);
+        }
+        return false;
+    };
+    return search(start) ? [...path] : [...component, start];
+}
+/* c8 ignore stop */
+/** Resolve a scalar parent spelling to the workspace's canonical identifier. */
+function resolveCanonicalScalarParent(parent, canonicalIdByLowercase) {
+    if (typeof parent !== "string")
+        return undefined;
+    const normalized = parent.trim().toLowerCase();
+    return normalized.length > 0
+        ? canonicalIdByLowercase.get(normalized)
+        : undefined;
+}
+/** Append dependency-backed child-to-parent adjacency for one holder. */
+function appendDependencyHierarchyEdges(item, graph, canonicalIdByLowercase, relationshipRegistry) {
+    for (const dependency of item.dependencies ?? []) {
+        if (typeof dependency !== "object" ||
+            dependency === null ||
+            typeof dependency.id !== "string")
+            continue;
+        const definition = relationshipRegistry.resolve(dependency.kind);
+        if (!definition?.hierarchy)
+            continue;
+        const target = canonicalIdByLowercase.get(dependency.id.toLowerCase());
+        if (!target)
+            continue;
+        if (definition.hierarchyDirection === "source_parent")
+            graph.get(target).push(item.id);
+        else
+            graph.get(item.id).push(target);
+    }
+}
+/** Build canonical child-to-parent adjacency across every hierarchy spelling. */
+export function buildLifecycleParentGraph(items, relationshipRegistry = resolveWorkspaceRelationshipKindRegistry()) {
+    const canonicalIdByLowercase = new Map(items.map((item) => [item.id.toLowerCase(), item.id]));
+    const graph = new Map(items.map((item) => [item.id, []]));
+    for (const item of [...items].sort((left, right) => left.id.localeCompare(right.id))) {
+        const edges = graph.get(item.id);
+        const canonicalParentId = resolveCanonicalScalarParent(item.parent, canonicalIdByLowercase);
+        if (canonicalParentId)
+            edges.push(canonicalParentId);
+        appendDependencyHierarchyEdges(item, graph, canonicalIdByLowercase, relationshipRegistry);
+    }
+    for (const [id, edges] of graph) {
+        graph.set(id, [...new Set(edges)].sort());
+    }
+    return graph;
+}
+/** Project shared hierarchy analysis into the validation result contract. */
+export function detectLifecycleParentCycles(items, statusRegistry, relationshipRegistry = resolveWorkspaceRelationshipKindRegistry()) {
+    const hierarchy = analyzeHierarchyIntegrity(items, (status) => statusRegistry
+        ? statusIsTerminal(status, statusRegistry)
+        : status === "closed" || status === "canceled", relationshipRegistry);
+    const graph = buildLifecycleParentGraph(items, relationshipRegistry);
+    const cycleComponents = hierarchy.cycles.map((cycle) => cycle.item_ids);
+    return {
+        cycle_count: cycleComponents.length,
+        active_cycle_count: hierarchy.cycles.filter((cycle) => !cycle.legacy_terminal).length,
+        legacy_cycle_count: hierarchy.cycles.filter((cycle) => cycle.legacy_terminal).length,
+        cycle_item_ids: [...new Set(cycleComponents.flat())].sort(),
+        cycle_sample_paths: cycleComponents.map((component) => resolveLifecycleDependencyCycleSamplePath(component, graph).join("->")),
+        cardinality_violation_count: hierarchy.cardinality_violations.length,
+        active_cardinality_violation_count: hierarchy.cardinality_violations.filter((finding) => !finding.legacy_terminal).length,
+        legacy_cardinality_violation_count: hierarchy.cardinality_violations.filter((finding) => finding.legacy_terminal).length,
+        cardinality_violation_rows: hierarchy.cardinality_violations.map((finding) => `${finding.child_id}:${finding.parent_ids.join(",")}:${finding.legacy_terminal ? "legacy" : "active"}`),
+        parent_divergence_count: hierarchy.divergences.length,
+        active_parent_divergence_count: hierarchy.divergences.filter((finding) => !finding.legacy_terminal).length,
+        legacy_parent_divergence_count: hierarchy.divergences.filter((finding) => finding.legacy_terminal).length,
+        parent_divergence_rows: hierarchy.divergences.map((finding) => `${finding.child_id}:scalar=${finding.scalar_parent_id}:dependencies=${finding.dependency_parent_ids.join(",")}:${finding.legacy_terminal ? "legacy" : "active"}`),
+    };
+}
+//# sourceMappingURL=hierarchy-validation.js.map
+//# debugId=77a3c404-bbcd-5a5e-80bf-cb61c45af55d

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

@@ -7,6 +7,7 @@ import type { ValidateMetadataProfile, ValidateMetadataRequiredField } from "../
 import { type OutputProjectionDeclaration } from "../output-projection.js";
 import { type RelationshipKindRegistry } from "../relationships.js";
 import { type ValidateItem } from "./validate-item-reader.js";
+import { buildLifecycleParentGraph, detectLifecycleParentCycles, resolveLifecycleDependencyCycleSamplePath } from "./hierarchy-validation.js";
 type ValidateCheckName = "metadata" | "resolution" | "lifecycle" | "dependency_references" | "files" | "command_references" | "history_drift" | "format_version" | "storage_integrity";
 type ValidateStatus = "ok" | "warn" | "error";
 type ValidateDependencyCycleSeverity = "off" | "warn" | "error";
@@ -198,18 +199,11 @@ declare function buildDependencyReferencesCheck(items: ItemWithBody[], verboseDi
 };
 declare function extractItemIds(value: string, idPrefix?: string): string[];
 declare function findLifecycleDependencyCycleComponents(graph: Map<string, string[]>): string[][];
-declare function resolveLifecycleDependencyCycleSamplePath(component: string[], graph: Map<string, string[]>): string[];
 declare function detectLifecycleDependencyCycles(activeItems: ItemWithBody[], idPrefix?: string): {
     cycle_count: number;
     cycle_item_ids: string[];
     cycle_sample_paths: string[];
 };
-declare function buildLifecycleParentGraph(items: ItemWithBody[], relationshipRegistry?: RelationshipKindRegistry): Map<string, string[]>;
-declare function detectLifecycleParentCycles(items: ItemWithBody[]): {
-    cycle_count: number;
-    cycle_item_ids: string[];
-    cycle_sample_paths: string[];
-};
 interface OrphanedPathRow {
     path: string;
     classification: OrphanedPathClassification;
@@ -237,10 +231,10 @@ declare function buildFilesCheck(items: ItemWithBody[], workspaceRoot: string, p
     warnings: string[];
     staleLinkPruneRows: StaleLinkPruneRow[];
 }>;
-declare function buildCommandReferencesCheck(items: ItemWithBody[], idPrefix: string, verboseDiagnostics: boolean): {
+declare function buildCommandReferencesCheck(items: ItemWithBody[], idPrefix: string, verboseDiagnostics: boolean, pmRoot: string): Promise<{
     check: ValidateCheck;
     warnings: string[];
-};
+}>;
 /** Apply one planned fix through the SAME audited command paths an operator would use by hand (`pm update` / `pm files --remove` / `pm docs --remove`), so every applied fix carries normal history, locking, and hook behavior. Command modules are imported lazily: plain validate runs stay read-only and never pay the mutation-stack import cost. */
 declare function applyValidateFix(fix: ValidateFixRecord, global: GlobalOptions, services: ValidateMutationServices): Promise<void>;
 declare function applyValidateFixes(applicable: ValidateFixRecord[], global: GlobalOptions, services: ValidateMutationServices): Promise<{

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]="1ed6b663-882a-5936-bd89-46bbbb17d806")}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]="aca69fd7-c47a-5424-b58f-f305f690edd9")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -42,8 +42,10 @@ import { createRelationshipKindRegistry, } from "../relationships.js";
 import { runDocs } from "../docs.js";
 import { runFiles } from "../files.js";
 import { extractReferencedPmItemIdsFromCommand } from "../test/linked-command-detection.js";
+import { resolveLinkedTestSourceRef, resolveLinkedTestSourceWorkspaceRoot, resolveLinkedTestTrustBatch, } from "../test/trust.js";
 import { readValidateItems, } from "./validate-item-reader.js";
 import { buildValidateHistoryDriftCheck } from "./validate-history-drift.js";
+import { buildLifecycleParentGraph, detectLifecycleParentCycles, resolveLifecycleDependencyCycleSamplePath, } from "./hierarchy-validation.js";
 const FILE_SCAN_DIRECTORIES = ["src", "tests", "docs"];
 const FILE_SCAN_ROOT_FILES = [
     "README.md",
@@ -1107,41 +1109,6 @@ function findLifecycleDependencyCycleComponents(graph) {
         left.join(",").localeCompare(right.join(",")));
 }
 /* c8 ignore stop */
-/* c8 ignore start -- cycle sample-path fallback branches are covered by lifecycle graph integration tests */
-function resolveLifecycleDependencyCycleSamplePath(component, graph) {
-    const start = component[0];
-    if (component.length === 1) {
-        return [start, start];
-    }
-    const componentSet = new Set(component);
-    const path = [start];
-    const visited = new Set([start]);
-    const search = (current) => {
-        const neighbors = (graph.get(current) ?? []).filter((candidate) => componentSet.has(candidate));
-        for (const next of neighbors) {
-            if (next === start && path.length > 1) {
-                path.push(start);
-                return true;
-            }
-            if (visited.has(next)) {
-                continue;
-            }
-            visited.add(next);
-            path.push(next);
-            if (search(next)) {
-                return true;
-            }
-            path.pop();
-            visited.delete(next);
-        }
-        return false;
-    };
-    if (search(start)) {
-        return [...path];
-    }
-    return [...component, start];
-}
-/* c8 ignore stop */
 function detectLifecycleDependencyCycles(activeItems, idPrefix = "pm") {
     const graph = buildLifecycleDependencyGraph(activeItems, idPrefix);
     const cycleComponents = findLifecycleDependencyCycleComponents(graph);
@@ -1153,62 +1120,6 @@ function detectLifecycleDependencyCycles(activeItems, idPrefix = "pm") {
         cycle_sample_paths: cycleSamplePaths,
     };
 }
-// Parent (composition) cycle detection (pm-8vul / GH-280). The dependency-cycle
-// path above only walks blocked_by/definition_of_ready edges across ACTIVE items;
-// it never traverses item.parent, so a parent cycle (A.parent=B, B.parent=A, or
-// any longer ring) goes undetected while it silently breaks `pm list --tree`,
-// orphan detection, and progress rollups. We reuse the generic Tarjan SCC helper
-// on a child->[parent] adjacency map. Unlike dependency cycles we scan ALL items
-// (not just active ones) because a parent cycle among closed items is still
-// structural corruption of the hierarchy.
-function buildLifecycleParentGraph(items, relationshipRegistry = createRelationshipKindRegistry()) {
-    // PR #279 made parent matching case-insensitive (e.g. `parent: PM-FK49`
-    // resolves to `id: pm-fk49`). Resolve parent references to their canonical
-    // item id the same way so a casing mismatch can never silently drop a cycle
-    // edge and hide a parent cycle (false negative).
-    const canonicalIdByLowercase = new Map(items.map((item) => [item.id.toLowerCase(), item.id]));
-    const graph = new Map(items.map((item) => [item.id, []]));
-    const sortedItems = [...items].sort((left, right) => left.id.localeCompare(right.id));
-    sortedItems.forEach((item) => {
-        const edges = graph.get(item.id);
-        const parentId = toMeaningfulString(item.parent);
-        const canonicalParentId = parentId
-            ? canonicalIdByLowercase.get(parentId.toLowerCase())
-            : undefined;
-        if (canonicalParentId) {
-            edges.push(canonicalParentId);
-        }
-        (item.dependencies ?? []).forEach((dependency) => {
-            const definition = relationshipRegistry.resolve(dependency.kind);
-            if (!definition?.hierarchy)
-                return;
-            const target = canonicalIdByLowercase.get(dependency.id.toLowerCase());
-            if (!target)
-                return;
-            if (definition.hierarchyDirection === "source_parent") {
-                graph.get(target).push(item.id);
-            }
-            else {
-                edges.push(target);
-            }
-        });
-    });
-    graph.forEach((edges, id) => {
-        graph.set(id, [...new Set(edges)].sort((left, right) => left.localeCompare(right)));
-    });
-    return graph;
-}
-function detectLifecycleParentCycles(items) {
-    const graph = buildLifecycleParentGraph(items);
-    const cycleComponents = findLifecycleDependencyCycleComponents(graph);
-    const cycleItemIds = [...new Set(cycleComponents.flat())].sort((left, right) => left.localeCompare(right));
-    const cycleSamplePaths = cycleComponents.map((component) => resolveLifecycleDependencyCycleSamplePath(component, graph).join("->"));
-    return {
-        cycle_count: cycleComponents.length,
-        cycle_item_ids: cycleItemIds,
-        cycle_sample_paths: cycleSamplePaths,
-    };
-}
 function classifyOrphanedPath(pathValue) {
     if (pathValue.startsWith("docs/")) {
         return "docs_unowned";
@@ -1435,7 +1346,10 @@ function lifecycleCycleWarningToken(prefix, severity, count) {
     }
     return `${severity === "error" ? `${prefix}_error` : prefix}:${count}`;
 }
-function buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, dependencyCycleCount, parentCycleCount) {
+function lifecycleAdvisoryWarningToken(prefix, severity, count) {
+    return count > 0 && severity !== "off" ? `${prefix}:${count}` : null;
+}
+function buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, counts) {
     const warnings = [];
     if (rows.closureLikeRows.length > 0) {
         warnings.push(`validate_lifecycle_active_closure_like_metadata:${rows.closureLikeRows.length}`);
@@ -1446,12 +1360,22 @@ function buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSever
     if (includeStaleBlockers && rows.staleBlockerRows.length > 0) {
         warnings.push(`validate_lifecycle_stale_blockers:${rows.staleBlockerRows.length}`);
     }
-    const dependencyWarning = lifecycleCycleWarningToken("validate_lifecycle_dependency_cycles", dependencyCycleSeverity, dependencyCycleCount);
-    const parentWarning = lifecycleCycleWarningToken("validate_hierarchy_parent_cycle", parentCycleSeverity, parentCycleCount);
+    const dependencyWarning = lifecycleCycleWarningToken("validate_lifecycle_dependency_cycles", dependencyCycleSeverity, counts.dependencyCycles);
+    const parentWarning = lifecycleCycleWarningToken("validate_hierarchy_parent_cycle", parentCycleSeverity, counts.activeHierarchyCycles);
+    const cardinalityWarning = lifecycleCycleWarningToken("validate_hierarchy_cardinality_violation", parentCycleSeverity, counts.activeHierarchyCardinality);
+    const divergenceWarning = lifecycleCycleWarningToken("validate_hierarchy_parent_divergence", parentCycleSeverity, counts.activeHierarchyDivergence);
+    const legacyCycleWarning = lifecycleAdvisoryWarningToken("validate_legacy_hierarchy_parent_cycle", parentCycleSeverity, counts.legacyHierarchyCycles);
+    const legacyCardinalityWarning = lifecycleAdvisoryWarningToken("validate_legacy_hierarchy_cardinality_violation", parentCycleSeverity, counts.legacyHierarchyCardinality);
+    const legacyDivergenceWarning = lifecycleAdvisoryWarningToken("validate_legacy_hierarchy_parent_divergence", parentCycleSeverity, counts.legacyHierarchyDivergence);
     return [
         ...warnings,
         ...(dependencyWarning ? [dependencyWarning] : []),
         ...(parentWarning ? [parentWarning] : []),
+        ...(cardinalityWarning ? [cardinalityWarning] : []),
+        ...(divergenceWarning ? [divergenceWarning] : []),
+        ...(legacyCycleWarning ? [legacyCycleWarning] : []),
+        ...(legacyCardinalityWarning ? [legacyCardinalityWarning] : []),
+        ...(legacyDivergenceWarning ? [legacyDivergenceWarning] : []),
     ];
 }
 function linkedArtifactPathExceedsFilesystemLimits(artifactPath) {
@@ -1557,8 +1481,16 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
     const rows = collectLifecycleScanRows(items, includeStaleBlockers, statusRegistry, lifecyclePatternPolicy);
     sortLifecycleScanRows(rows);
     const dependencyCycleDiagnostics = detectLifecycleDependencyCycles(rows.activeItems, idPrefix);
-    const parentCycleDiagnostics = detectLifecycleParentCycles(items);
-    const warnings = buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, dependencyCycleDiagnostics.cycle_count, parentCycleDiagnostics.cycle_count);
+    const parentCycleDiagnostics = detectLifecycleParentCycles(items, statusRegistry);
+    const warnings = buildLifecycleWarnings(rows, includeStaleBlockers, dependencyCycleSeverity, parentCycleSeverity, {
+        dependencyCycles: dependencyCycleDiagnostics.cycle_count,
+        activeHierarchyCycles: parentCycleDiagnostics.active_cycle_count,
+        activeHierarchyCardinality: parentCycleDiagnostics.active_cardinality_violation_count,
+        activeHierarchyDivergence: parentCycleDiagnostics.active_parent_divergence_count,
+        legacyHierarchyCycles: parentCycleDiagnostics.legacy_cycle_count,
+        legacyHierarchyCardinality: parentCycleDiagnostics.legacy_cardinality_violation_count,
+        legacyHierarchyDivergence: parentCycleDiagnostics.legacy_parent_divergence_count,
+    });
     const diagnosticLimit = verboseDiagnostics
         ? Number.POSITIVE_INFINITY
         : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
@@ -1569,9 +1501,14 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
     const summarizedDependencyCycleSamplePaths = summarizeList(dependencyCycleDiagnostics.cycle_sample_paths, diagnosticLimit);
     const summarizedParentCycleItemIds = summarizeList(parentCycleDiagnostics.cycle_item_ids, diagnosticLimit);
     const summarizedParentCycleSamplePaths = summarizeList(parentCycleDiagnostics.cycle_sample_paths, diagnosticLimit);
+    const summarizedHierarchyCardinalityRows = summarizeList(parentCycleDiagnostics.cardinality_violation_rows, diagnosticLimit);
+    const summarizedHierarchyDivergenceRows = summarizeList(parentCycleDiagnostics.parent_divergence_rows, diagnosticLimit);
     const hasErrorSeverityCycle = (dependencyCycleDiagnostics.cycle_count > 0 &&
         dependencyCycleSeverity === "error") ||
-        (parentCycleDiagnostics.cycle_count > 0 && parentCycleSeverity === "error");
+        ((parentCycleDiagnostics.active_cycle_count > 0 ||
+            parentCycleDiagnostics.active_cardinality_violation_count > 0 ||
+            parentCycleDiagnostics.active_parent_divergence_count > 0) &&
+            parentCycleSeverity === "error");
     return {
         check: {
             name: "lifecycle",
@@ -1602,11 +1539,23 @@ function buildLifecycleCheck(items, includeStaleBlockers, dependencyCycleSeverit
                 dependency_cycle_sample_paths_truncated: summarizedDependencyCycleSamplePaths.truncated,
                 parent_cycle_severity_policy: parentCycleSeverity,
                 parent_cycle_count: parentCycleDiagnostics.cycle_count,
+                active_parent_cycle_count: parentCycleDiagnostics.active_cycle_count,
+                legacy_parent_cycle_count: parentCycleDiagnostics.legacy_cycle_count,
                 parent_cycle_item_count: parentCycleDiagnostics.cycle_item_ids.length,
                 parent_cycle_item_ids: summarizedParentCycleItemIds.values,
                 parent_cycle_item_ids_truncated: summarizedParentCycleItemIds.truncated,
                 parent_cycle_sample_paths: summarizedParentCycleSamplePaths.values,
                 parent_cycle_sample_paths_truncated: summarizedParentCycleSamplePaths.truncated,
+                hierarchy_cardinality_violation_count: parentCycleDiagnostics.cardinality_violation_count,
+                active_hierarchy_cardinality_violation_count: parentCycleDiagnostics.active_cardinality_violation_count,
+                legacy_hierarchy_cardinality_violation_count: parentCycleDiagnostics.legacy_cardinality_violation_count,
+                hierarchy_cardinality_violation_rows: summarizedHierarchyCardinalityRows.values,
+                hierarchy_cardinality_violation_rows_truncated: summarizedHierarchyCardinalityRows.truncated,
+                hierarchy_parent_divergence_count: parentCycleDiagnostics.parent_divergence_count,
+                active_hierarchy_parent_divergence_count: parentCycleDiagnostics.active_parent_divergence_count,
+                legacy_hierarchy_parent_divergence_count: parentCycleDiagnostics.legacy_parent_divergence_count,
+                hierarchy_parent_divergence_rows: summarizedHierarchyDivergenceRows.values,
+                hierarchy_parent_divergence_rows_truncated: summarizedHierarchyDivergenceRows.truncated,
                 stale_blocker_reason_patterns: [
                     ...lifecyclePatternPolicy.stale_blocker_reason_patterns,
                 ],
@@ -1762,23 +1711,40 @@ async function buildFilesCheck(items, workspaceRoot, pmRoot, fileScanMode, inclu
     };
 }
 /* c8 ignore stop */
-/* c8 ignore start -- command preview truncation formatting is covered by command-reference integration fixtures */
-function summarizeCommandReferenceRow(ownerId, referencedId, command) {
+/** Collapse a linked command to the bounded preview used in validation rows. */
+function summarizeCommandPreview(command) {
     const normalizedCommand = command.trim().replaceAll(/\s+/g, " ");
-    const commandPreview = normalizedCommand.length > 120
+    return normalizedCommand.length > 120
         ? `${normalizedCommand.slice(0, 117)}...`
         : normalizedCommand;
-    return `${ownerId}:${referencedId}:${commandPreview}`;
 }
-/* c8 ignore stop */
+/** Join command-reference identity and its bounded preview for diagnostics. */
+function summarizeCommandReferenceRow(ownerId, referencedId, command) {
+    return `${ownerId}:${referencedId}:${summarizeCommandPreview(command)}`;
+}
+/** Render portable diagnostics for linked tests that this clone has not trusted. */
+function buildUntrustedLinkedTestRows(linkedTests, trustDecisions) {
+    const rows = [];
+    linkedTests.forEach(({ item, linkedTest }, index) => {
+        const trust = trustDecisions[index];
+        if (trust.trusted)
+            return;
+        const command = summarizeCommandPreview(linkedTest.command ?? "");
+        rows.push(`${item.id}:${trust.source_ref ?? "unknown"}->${trust.current_source_ref ?? "unknown"}:${command}`);
+    });
+    return rows;
+}
 /* c8 ignore start -- command-reference discovery/stale-id permutations are covered by linked-test integration suites */
-function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
+async function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics, pmRoot) {
     const knownIds = new Set(items.map((item) => item.id.toLowerCase()));
     let linkedCommandsScanned = 0;
     let referencedPmIdCount = 0;
     const referencedPmIds = new Set();
     const staleReferenceRows = [];
     const linkedTests = items.flatMap((item) => (item.tests ?? []).map((linkedTest) => ({ item, linkedTest })));
+    const currentSourceRef = await resolveLinkedTestSourceRef(resolveLinkedTestSourceWorkspaceRoot());
+    const trustDecisions = await resolveLinkedTestTrustBatch(pmRoot, linkedTests.map(({ linkedTest }) => linkedTest), currentSourceRef);
+    const untrustedRows = buildUntrustedLinkedTestRows(linkedTests, trustDecisions);
     for (const { item, linkedTest } of linkedTests) {
         if (typeof linkedTest.command !== "string" ||
             linkedTest.command.trim().length === 0) {
@@ -1803,17 +1769,20 @@ function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
     ]
         .filter((value) => value.length > 0)
         .sort((left, right) => left.localeCompare(right));
-    const warnings = uniqueStaleReferenceRows.length > 0
-        ? [
-            `validate_command_references_stale_pm_ids:${uniqueStaleReferenceRows.length}`,
-        ]
-        : [];
+    const warnings = [];
+    if (uniqueStaleReferenceRows.length > 0) {
+        warnings.push(`validate_command_references_stale_pm_ids:${uniqueStaleReferenceRows.length}`);
+    }
+    if (untrustedRows.length > 0) {
+        warnings.push(`validate_linked_test_trust_unacknowledged:${untrustedRows.length}`);
+    }
     const diagnosticLimit = verboseDiagnostics
         ? Number.POSITIVE_INFINITY
         : DIAGNOSTIC_LIST_SUMMARY_LIMIT;
     const summarizedRows = summarizeList(uniqueStaleReferenceRows, diagnosticLimit);
     const summarizedStalePmIds = summarizeList(stalePmIds, diagnosticLimit);
     const summarizedReferencedPmIds = summarizeList([...referencedPmIds].sort((left, right) => left.localeCompare(right)), diagnosticLimit);
+    const summarizedUntrustedRows = summarizeList(untrustedRows, diagnosticLimit);
     return {
         check: {
             name: "command_references",
@@ -1826,6 +1795,10 @@ function buildCommandReferencesCheck(items, idPrefix, verboseDiagnostics) {
                 unique_referenced_pm_ids_count: referencedPmIds.size,
                 unique_referenced_pm_ids: summarizedReferencedPmIds.values,
                 unique_referenced_pm_ids_truncated: summarizedReferencedPmIds.truncated,
+                linked_test_trust_current_source_ref: currentSourceRef ?? null,
+                untrusted_linked_tests_count: untrustedRows.length,
+                untrusted_linked_tests: summarizedUntrustedRows.values,
+                untrusted_linked_tests_truncated: summarizedUntrustedRows.truncated,
                 stale_pm_id_references_count: uniqueStaleReferenceRows.length,
                 stale_pm_ids_count: stalePmIds.length,
                 stale_pm_ids: summarizedStalePmIds.values,
@@ -2145,7 +2118,7 @@ async function executeRequestedValidateChecks(params) {
         recordValidateCheck(state, built, fixHintsEnabled);
     }
     if (params.requestedChecks.has("command_references")) {
-        recordValidateCheck(state, buildCommandReferencesCheck(params.items, params.settings.id_prefix, fullDiagnostics), fixHintsEnabled);
+        recordValidateCheck(state, await buildCommandReferencesCheck(params.items, params.settings.id_prefix, fullDiagnostics, params.pmRoot), fixHintsEnabled);
     }
     if (params.requestedChecks.has("history_drift")) {
         recordValidateCheck(state, await buildValidateHistoryDriftCheck(params.pmRoot, params.items, fullDiagnostics), fixHintsEnabled);
@@ -2307,4 +2280,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=1ed6b663-882a-5936-bd89-46bbbb17d806
+//# debugId=aca69fd7-c47a-5424-b58f-f305f690edd9

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

@@ -11,6 +11,8 @@
  */
 import type { Dependency, ItemStatus } from "../../types/index.js";
 import { RelationshipGraph, type RelationshipKindRegistry } from "../relationships.js";
+import { type HierarchyIntegrityAnalysis } from "./hierarchy-integrity.js";
+export { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
 /** Minimal item shape inspected by dependency-reference governance. */
 export interface DependencyReferenceHolder {
     /** Stable item identifier. */
@@ -61,7 +63,6 @@ export declare function normalizeDependencyGraphTarget(target: unknown): string
  * share this resolution so custom ordering semantics apply identically on
  * every surface.
  */
-export declare function resolveWorkspaceRelationshipKindRegistry(): RelationshipKindRegistry;
 /** One raw stored dependency row duplicated verbatim on a single holder. */
 export interface DuplicateDependencyRow {
     /** Item that stores the duplicated row. */
@@ -152,7 +153,11 @@ export interface WorkspaceRelationshipAssembly {
     orderingContradictions?: OrderingStorageContradiction[];
     /** Raw legacy alias rows grouped by accepted spelling before graph canonicalization. */
     legacyAliasCounts: Record<string, number>;
+    /** Shared hierarchy analysis retained across ordinary object spread copies. */
+    hierarchyIntegrity?: HierarchyIntegrityAnalysis;
 }
+/** Read the hierarchy analysis paired with an assembly created by this module. */
+export declare function getWorkspaceHierarchyIntegrity(assembly: WorkspaceRelationshipAssembly): HierarchyIntegrityAnalysis | undefined;
 /** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
 export declare function collectLegacyDependencyAliasCounts(items: readonly DependencyReferenceHolder[], registry?: RelationshipKindRegistry): Record<string, number>;
 /**

package/dist/sdk/graph/assembly.js

@@ -1,8 +1,10 @@
 
-!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]="a6fc5da1-b7d1-5b3c-8033-cecccc7861c3")}catch(e){}}();
-import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { RelationshipGraph, createRelationshipKindRegistry, } from "../relationships.js";
+!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]="9a6974b3-63d7-5dc7-8329-0f15f0dc83ec")}catch(e){}}();
+import { RelationshipGraph, } from "../relationships.js";
 import { isExternalDependencySourceKind } from "../dependency-provenance.js";
+import { analyzeHierarchyIntegrity, } from "./hierarchy-integrity.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
+export { resolveWorkspaceRelationshipKindRegistry } from "./workspace-relationship-kind-registry.js";
 /** Normalize a decoded reference target and reject empty legacy placeholders. */
 function normalizeDependencyReferenceTarget(target) {
     if (typeof target !== "string")
@@ -20,23 +22,6 @@ export function normalizeDependencyGraphTarget(target) {
         ? undefined
         : normalized;
 }
-/**
- * Resolve the default workspace relationship-kind registry: the built-in kinds
- * merged with every active extension-contributed relationship-kind
- * registration. Assembly, mutation advisories, and standalone graph consumers
- * share this resolution so custom ordering semantics apply identically on
- * every surface.
- */
-export function resolveWorkspaceRelationshipKindRegistry() {
-    const registry = createRelationshipKindRegistry();
-    for (const registration of getActiveExtensionRegistrations()
-        ?.relationship_kinds ?? []) {
-        for (const definition of registration.definitions) {
-            registry.register(definition);
-        }
-    }
-    return registry;
-}
 /** Compare text case-insensitively with an exact-spelling deterministic tie-breaker. */
 function compareCaseFoldedText(left, right) {
     const normalizedLeft = left.toLowerCase();
@@ -242,6 +227,11 @@ export function collectExternalDependencyTargetIds(items) {
     }
     return [...targets.values()].sort((left, right) => left.localeCompare(right));
 }
+const hierarchyIntegrityByAssembly = new WeakMap();
+/** Read the hierarchy analysis paired with an assembly created by this module. */
+export function getWorkspaceHierarchyIntegrity(assembly) {
+    return assembly.hierarchyIntegrity ?? hierarchyIntegrityByAssembly.get(assembly);
+}
 /** Count raw dependency rows that use a registered compatibility alias instead of its canonical kind. */
 export function collectLegacyDependencyAliasCounts(items, registry = resolveWorkspaceRelationshipKindRegistry()) {
     const counts = {};
@@ -316,7 +306,8 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
             dependencies,
         };
     });
-    return {
+    const hierarchyIntegrity = analyzeHierarchyIntegrity(safeItems, isTerminal, relationshipRegistry);
+    const assembly = {
         graph: RelationshipGraph.fromItems([
             ...graphItems,
             ...missingIds.map((id) => ({ id })),
@@ -349,7 +340,10 @@ export function assembleWorkspaceRelationshipGraph(items, isTerminal, registry)
         duplicateRows: collectDuplicateDependencyRows(safeItems, isTerminal),
         orderingContradictions: collectOrderingStorageContradictions(safeItems, isTerminal, relationshipRegistry),
         legacyAliasCounts: collectLegacyDependencyAliasCounts(safeItems, relationshipRegistry),
+        hierarchyIntegrity,
     };
+    hierarchyIntegrityByAssembly.set(assembly, hierarchyIntegrity);
+    return assembly;
 }
 //# sourceMappingURL=assembly.js.map
-//# debugId=a6fc5da1-b7d1-5b3c-8033-cecccc7861c3
+//# debugId=9a6974b3-63d7-5dc7-8329-0f15f0dc83ec

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

@@ -7,6 +7,6 @@
  * drifting when a finding family is added.
  */
 /** Stable machine-readable relationship audit finding families. */
-export declare const RELATIONSHIP_AUDIT_FINDING_CODES: readonly ["missing_reference_active", "missing_reference_terminal", "legacy_no_blocker_sentinel", "ordering_cycle", "legacy_ordering_cycle", "ordering_storage_contradiction", "legacy_ordering_storage_contradiction", "duplicate_edge", "legacy_duplicate_edge", "duplicate_dependency_row", "legacy_duplicate_dependency_row", "stale_lifecycle_block", "isolated_active_node", "sparse_active_node"];
+export declare const RELATIONSHIP_AUDIT_FINDING_CODES: readonly ["missing_reference_active", "missing_reference_terminal", "legacy_no_blocker_sentinel", "ordering_cycle", "legacy_ordering_cycle", "ordering_storage_contradiction", "legacy_ordering_storage_contradiction", "hierarchy_cycle", "legacy_hierarchy_cycle", "hierarchy_cardinality_violation", "legacy_hierarchy_cardinality_violation", "hierarchy_direction_violation", "legacy_hierarchy_direction_violation", "duplicate_edge", "legacy_duplicate_edge", "duplicate_dependency_row", "legacy_duplicate_dependency_row", "stale_lifecycle_block", "isolated_active_node", "sparse_active_node"];
 /** Machine-readable identifier for one relationship audit finding family. */
 export type RelationshipAuditFindingCode = (typeof RELATIONSHIP_AUDIT_FINDING_CODES)[number];

package/dist/sdk/graph/governance-contracts.js

@@ -8,7 +8,7 @@
  */
 /** Stable machine-readable relationship audit finding families. */
 
-!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]="bc561e73-75b8-5ea7-a18c-da70fb991b69")}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]="a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72")}catch(e){}}();
 export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "missing_reference_active",
     "missing_reference_terminal",
@@ -17,6 +17,12 @@ export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "legacy_ordering_cycle",
     "ordering_storage_contradiction",
     "legacy_ordering_storage_contradiction",
+    "hierarchy_cycle",
+    "legacy_hierarchy_cycle",
+    "hierarchy_cardinality_violation",
+    "legacy_hierarchy_cardinality_violation",
+    "hierarchy_direction_violation",
+    "legacy_hierarchy_direction_violation",
     "duplicate_edge",
     "legacy_duplicate_edge",
     "duplicate_dependency_row",
@@ -26,4 +32,4 @@ export const RELATIONSHIP_AUDIT_FINDING_CODES = [
     "sparse_active_node",
 ];
 //# sourceMappingURL=governance-contracts.js.map
-//# debugId=bc561e73-75b8-5ea7-a18c-da70fb991b69
+//# debugId=a8bc0ebd-e5e4-57f3-8e6c-417f9809eb72