@unbrained/pm-cli 2026.8.21 → 2026.8.22

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

@@ -7,6 +7,7 @@ import { type HistoryAuthorAttributionScan } from "../author-attribution.js";
 import type { PmSettings } from "../../types/index.js";
 import { buildCapabilityContractMetadata, collectUnknownCapabilityGuidance } from "../extension/doctor.js";
 import { type StaleInProgressScan } from "./stale-work.js";
+import { type HierarchyIntegrityAnalysis } from "../graph/hierarchy-integrity.js";
 type HealthStatus = "ok" | "warn";
 type MigrationRuntimeStatus = "pending" | "failed" | "applied";
 /** Documents the health check payload exchanged by command, SDK, and package integrations. */
@@ -145,6 +146,7 @@ declare function normalizeExtensionNameForMatch(value: string): string;
 declare function isExpectedUnmanagedExtension(name: string, directory: string): boolean;
 declare function isDirectory(targetPath: string): Promise<boolean>;
 declare function listItemDocumentPaths(pmRoot: string, typeToFolder: Record<string, string>): Promise<string[]>;
+declare function buildHierarchyIntegrityWarnings(analysis: HierarchyIntegrityAnalysis): string[];
 declare function buildExtensionHealthTriageSummary(warnings: string[], loadFailureCount: number, activationFailureCount: number, migrationStatus: MigrationStatusSummary, managedStateWarningCount: number, managedExtensionEntriesCount: number, unmanagedLoadedExtensions: string[], unmanagedExpectedExtensions: string[], unmanagedActionRequiredExtensions: string[]): ExtensionHealthTriageSummary;
 declare function summarizeRecordList(value: unknown, limit: number): {
     count: number;
@@ -218,6 +220,7 @@ declare function projectHealthResult(result: HealthResult, options: RunHealthOpt
 export declare function runHealth(global: GlobalOptions, options?: RunHealthOptions): Promise<HealthResult>;
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyHealthCommand: {
+    buildHierarchyIntegrityWarnings: typeof buildHierarchyIntegrityWarnings;
     buildExtensionHealthTriageSummary: typeof buildExtensionHealthTriageSummary;
     buildHealthFindings: typeof buildHealthFindings;
     buildCapabilityContractMetadata: typeof buildCapabilityContractMetadata;

package/dist/sdk/governance/health.js

@@ -4,11 +4,13 @@
  * 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]="a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c")}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]="f7b3ff92-1fc7-55e9-aa76-af956714998f")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
+import { isTerminalStatus } from "../../core/item/status.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
+import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
 import { isFileMissingError, readFileIfExists, } from "../../core/fs/fs-utils.js";
 import { activateExtensions, getActiveExtensionRegistrations, loadExtensions, runActiveOnReadHooks, } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
@@ -44,6 +46,8 @@ import { scanStaleInProgressItems, } from "./stale-work.js";
 import { scanTrackedRuntimeCache } from "./tracked-runtime-cache.js";
 import { auditMergeDriverConfiguration, findGitWorkspaceRoot, } from "../merge/install.js";
 import { listMergeReceipts, partitionMergeReceipts, } from "../merge/receipts.js";
+import { resolveWorkspaceRelationshipKindRegistry } from "../graph/assembly.js";
+import { analyzeHierarchyIntegrity, } from "../graph/hierarchy-integrity.js";
 const PM_TELEMETRY_SOURCE_CONTEXT_SET = new Set(PM_TELEMETRY_SOURCE_CONTEXT_VALUES);
 const STALE_VECTORIZATION_SUMMARY_LIMIT = 25;
 const BRIEF_HEALTH_DETAIL_LIMIT = 8;
@@ -61,6 +65,7 @@ const TELEMETRY_SERVER_MAX_SCHEMA_VERSION_HEADERS = [
 function isAdvisoryHealthWarning(warning, requireMergeDrivers = false) {
     return (warning.startsWith("telemetry_") ||
         warning.startsWith("history_stream_over_compact_threshold:") ||
+        warning.startsWith("integrity_legacy_hierarchy_") ||
         warning.startsWith("stale_in_progress_items:") ||
         warning.startsWith("provenance_resolver_zero_success:") ||
         warning.startsWith("provenance_value_domain_invalid:") ||
@@ -315,10 +320,25 @@ async function scanHistoryIntegrity(pmRoot) {
     }
     return { files, unreadable, conflictMarkers, invalidJson };
 }
-async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers) {
+function buildHierarchyIntegrityWarnings(analysis) {
+    return [
+        ...analysis.cycles.map((cycle) => cycle.legacy_terminal
+            ? `integrity_legacy_hierarchy_cycle:${cycle.item_ids.join(",")}`
+            : `integrity_hierarchy_cycle:${cycle.item_ids.join(",")}`),
+        ...analysis.cardinality_violations.map((finding) => finding.legacy_terminal
+            ? `integrity_legacy_hierarchy_cardinality:${finding.child_id}`
+            : `integrity_hierarchy_cardinality:${finding.child_id}`),
+        ...analysis.divergences.map((finding) => finding.legacy_terminal
+            ? `integrity_legacy_hierarchy_divergence:${finding.child_id}`
+            : `integrity_hierarchy_divergence:${finding.child_id}`),
+    ];
+}
+async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDrivers, items) {
     const itemScan = await scanItemIntegrity(pmRoot, typeToFolder, schema);
     const historyScan = await scanHistoryIntegrity(pmRoot);
     const formatVersionScan = scanItemFormatVersions(itemScan.formatVersions);
+    const statusRegistry = resolveRuntimeStatusRegistry(schema);
+    const hierarchyIntegrity = analyzeHierarchyIntegrity(items, (status) => isTerminalStatus(status, statusRegistry), resolveWorkspaceRelationshipKindRegistry());
     const trackedRuntimeCache = await scanTrackedRuntimeCache(pmRoot);
     const gitWorkspaceRoot = await findGitWorkspaceRoot(pmRoot);
     const mergeDriverAudit = gitWorkspaceRoot === null
@@ -345,6 +365,7 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
         ...formatVersionScan.outdated.map((entry) => `integrity_item_outdated_format_version:${entry}`),
         /* c8 ignore stop */
         ...formatVersionScan.ahead.map((entry) => `integrity_item_ahead_format_version:${entry}`),
+        ...buildHierarchyIntegrityWarnings(hierarchyIntegrity),
         ...(trackedRuntimeCache.tracked_path_count > 0
             ? [
                 `tracked_runtime_cache_files:${trackedRuntimeCache.tracked_path_count}`,
@@ -360,11 +381,12 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
             : []),
     ];
     const normalizedWarnings = [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+    const actionableWarnings = normalizedWarnings.filter((warning) => !warning.startsWith("integrity_legacy_hierarchy_"));
     return {
         check: {
             name: "integrity",
-            status: normalizedWarnings.length === 0 ? "ok" : "warn",
-            ok: normalizedWarnings.length === 0,
+            status: actionableWarnings.length === 0 ? "ok" : "warn",
+            ok: actionableWarnings.length === 0,
             details: {
                 checked_item_files: itemScan.paths.length,
                 checked_history_streams: historyScan.files.length,
@@ -377,6 +399,9 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                     history_invalid_json: historyScan.invalidJson.length,
                     item_outdated_format_version: formatVersionScan.outdated.length,
                     item_ahead_format_version: formatVersionScan.ahead.length,
+                    hierarchy_cycles: hierarchyIntegrity.cycles.length,
+                    hierarchy_cardinality_violations: hierarchyIntegrity.cardinality_violations.length,
+                    hierarchy_parent_divergences: hierarchyIntegrity.divergences.length,
                     tracked_runtime_cache_files: trackedRuntimeCache.tracked_path_count,
                     merge_driver_configuration: mergeDriverAudit === null || mergeDriverAudit.status === "ok"
                         ? 0
@@ -390,6 +415,10 @@ async function buildIntegrityCheck(pmRoot, typeToFolder, schema, requireMergeDri
                 item_parse_failures: itemScan.parseFailures,
                 item_outdated_format_version: formatVersionScan.outdated,
                 item_ahead_format_version: formatVersionScan.ahead,
+                hierarchy_integrity: {
+                    ...hierarchyIntegrity,
+                    relations: summarizeRecordList(hierarchyIntegrity.relations, BRIEF_HEALTH_DETAIL_LIMIT),
+                },
                 history_unreadable: historyScan.unreadable,
                 history_conflict_markers: historyScan.conflictMarkers,
                 history_invalid_json: historyScan.invalidJson,
@@ -1832,7 +1861,9 @@ function extractHistoryDriftedCount(historyDriftCheck) {
 function buildHealthRemediationSources(params) {
     return {
         settings: params.normalizedSettingsReadWarnings,
-        directories: params.directoryState.missingDirs.map((dir) => `missing_directory:${dir}`).concat(params.directoryState.hookWarnings),
+        directories: params.directoryState.missingDirs
+            .map((dir) => `missing_directory:${dir}`)
+            .concat(params.directoryState.hookWarnings),
         settings_values: params.settingWarnings,
         telemetry: params.telemetryCheck.warnings,
         extensions: params.extensionCheck.warnings,
@@ -2000,7 +2031,7 @@ export async function runHealth(global, options = {}) {
     const locksCheck = await buildLocksCheck(pmRoot);
     const integrityCheck = skipPolicy.skipIntegrity
         ? buildSkippedHealthCheck("integrity")
-        : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true);
+        : await buildIntegrityCheck(pmRoot, typeRegistry.type_to_folder, settings.schema, options.requireMergeDrivers === true, items);
     const historyDriftCheck = skipPolicy.skipDrift
         ? buildSkippedHealthCheck("history_drift")
         : await buildHistoryDriftCheck(pmRoot, itemsWithBody);
@@ -2082,6 +2113,7 @@ export async function runHealth(global, options = {}) {
 }
 /** Public contract for test only health command, shared by SDK and presentation-layer consumers. */
 export const _testOnlyHealthCommand = {
+    buildHierarchyIntegrityWarnings,
     buildExtensionHealthTriageSummary,
     buildHealthFindings,
     buildCapabilityContractMetadata,
@@ -2110,4 +2142,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c
+//# debugId=f7b3ff92-1fc7-55e9-aa76-af956714998f

package/dist/sdk/governance/hierarchy-validation.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @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.
+ */
+import { type RuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
+import type { RelationshipKindRegistry } from "../relationships.js";
+import type { ValidateItem } from "./validate-item-reader.js";
+/** Resolve one deterministic closed walk through a known cycle component. */
+export declare function resolveLifecycleDependencyCycleSamplePath(component: string[], graph: Map<string, string[]>): string[];
+/** Build canonical child-to-parent adjacency across every hierarchy spelling. */
+export declare function buildLifecycleParentGraph(items: ValidateItem[], relationshipRegistry?: RelationshipKindRegistry): Map<string, string[]>;
+/** Project shared hierarchy analysis into the validation result contract. */
+export declare function detectLifecycleParentCycles(items: ValidateItem[], statusRegistry?: RuntimeStatusRegistry, relationshipRegistry?: RelationshipKindRegistry): {
+    cycle_count: number;
+    active_cycle_count: number;
+    legacy_cycle_count: number;
+    cycle_item_ids: string[];
+    cycle_sample_paths: string[];
+    cardinality_violation_count: number;
+    active_cardinality_violation_count: number;
+    legacy_cardinality_violation_count: number;
+    cardinality_violation_rows: string[];
+    parent_divergence_count: number;
+    active_parent_divergence_count: number;
+    legacy_parent_divergence_count: number;
+    parent_divergence_rows: string[];
+};

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;

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]="87e3932d-26f0-5d44-ac35-5d0d7d1f4467")}catch(e){}}();
 import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
@@ -44,6 +44,7 @@ import { runFiles } from "../files.js";
 import { extractReferencedPmItemIdsFromCommand } from "../test/linked-command-detection.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 +1108,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 +1119,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 +1345,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 +1359,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 +1480,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 +1500,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 +1538,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,
                 ],
@@ -2307,4 +2255,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=1ed6b663-882a-5936-bd89-46bbbb17d806
+//# debugId=87e3932d-26f0-5d44-ac35-5d0d7d1f4467

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>;
 /**