@unbrained/pm-cli 2026.8.20 → 2026.8.22

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

@@ -7,14 +7,14 @@ 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";
 type ValidateFileScanMode = "default" | "tracked-all" | "tracked-all-strict";
 type ItemWithBody = ValidateItem;
 type OrphanedPathClassification = "docs_unowned" | "tests_unowned" | "source_unowned" | "unlinked_existing";
-declare const LIFECYCLE_PATTERN_FIELD_KEYS: readonly ["blocked_reason", "resolution", "actual_result"];
-type LifecyclePatternFieldKey = (typeof LIFECYCLE_PATTERN_FIELD_KEYS)[number];
+type LifecyclePatternFieldKey = "blocked_reason" | "resolution" | "actual_result";
 /** Documents the validate command options payload exchanged by command, SDK, and package integrations. */
 export interface ValidateCommandOptions {
     /** Value that configures or reports check metadata for this contract. */
@@ -199,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,8 @@
  * 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]="b8c4707f-5445-5079-96e5-dc0dbd649b34")}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";
 import { execFile } from "node:child_process";
@@ -13,7 +14,7 @@ import { promisify } from "node:util";
 import { buildRemediationCommands } from "../../core/diagnostics/remediation.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../../core/extensions/item-fields.js";
-import { isFileMissingError, pathExists } from "../../core/fs/fs-utils.js";
+import { isFileMissingError } from "../../core/fs/fs-utils.js";
 import { normalizeStatusInput } from "../../core/item/status.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry, } from "../../core/schema/runtime-schema.js";
@@ -22,7 +23,7 @@ import { PmCliError } from "../../core/shared/errors.js";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
 import { nowIso } from "../../core/shared/time.js";
 import { CURRENT_ITEM_FORMAT_VERSION, effectiveItemFormatVersion, scanItemFormatVersions, } from "../../core/item/item-format-version.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { partitionFixesByGrant, planCloseReasonBackfillFixes, planEstimateBackfillFixes, planResolutionBackfillFixes, planStaleLinkPruneFixes, planTerminalParentFixes, resolveGrantedFixScopes, toFixOutputRow, } from "../../core/validate/fix-planning.js";
 import { findDuplicateIssueCodes, } from "../../core/governance/issue-codes.js";
@@ -43,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",
@@ -78,11 +80,6 @@ const VALIDATE_DEPENDENCY_CYCLE_SEVERITY_VALUES = [
     "warn",
     "error",
 ];
-const LIFECYCLE_PATTERN_FIELD_KEYS = [
-    "blocked_reason",
-    "resolution",
-    "actual_result",
-];
 const CORE_METADATA_REQUIRED_FIELDS = [
     "author",
     "acceptance_criteria",
@@ -1111,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);
@@ -1157,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";
@@ -1439,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}`);
@@ -1450,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) {
@@ -1561,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;
@@ -1573,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",
@@ -1606,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,
                 ],
@@ -2226,9 +2170,7 @@ export async function runValidate(options, global, services = {}) {
     // Resolved up-front so unknown --fix-scope values fail fast before any scan.
     const grantedFixScopes = resolveGrantedFixScopes(options.fixScope);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
@@ -2313,4 +2255,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=b8c4707f-5445-5079-96e5-dc0dbd649b34
+//# 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>;
 /**

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

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

@@ -12,7 +12,7 @@
  * carries a deterministic bounded sample, and proposes a safe next action so
  * agents can plan remediation without re-deriving context.
  */
-import type { RelationshipEdge } from "../relationships.js";
+import type { RelationshipEdge, RelationshipOutcomeTraversal } from "../relationships.js";
 import type { OrderingStorageContradiction, WorkspaceRelationshipAssembly } from "./assembly.js";
 import { type RelationshipAuditFindingCode } from "./governance-contracts.js";
 export type { RelationshipAuditFindingCode } from "./governance-contracts.js";
@@ -88,17 +88,19 @@ export interface RelationshipCoverageProfile {
     bridge_edges: number;
     /** Milestone nodes whose title explicitly declares an outcome. */
     outcome_nodes: number;
-    /** Active non-outcome nodes with a typed hierarchy or implements path to an outcome. */
+    /** Declared edge kinds and directions admitted by typed outcome reachability. */
+    outcome_reachability_basis: Record<RelationshipOutcomeTraversal, string>;
+    /** Active non-outcome nodes with a path admitted by outcome_reachability_basis. */
     active_outcome_reachable_nodes: number;
-    /** Active non-outcome nodes without a typed hierarchy or implements path to an outcome. */
+    /** Active non-outcome nodes without a path admitted by outcome_reachability_basis. */
     active_outcome_unreachable_nodes: number;
     /** Active typed-outcome reachability expressed as integer basis points. */
     active_outcome_reachability_basis_points: number;
     /** Terminal non-placeholder, non-outcome nodes included in the all-status census. */
     terminal_nodes: number;
-    /** Terminal non-outcome nodes with a typed hierarchy or implements path to an outcome. */
+    /** Terminal non-outcome nodes with a path admitted by outcome_reachability_basis. */
     terminal_outcome_reachable_nodes: number;
-    /** Terminal non-outcome nodes without a typed hierarchy or implements path to an outcome. */
+    /** Terminal non-outcome nodes without a path admitted by outcome_reachability_basis. */
     terminal_outcome_unreachable_nodes: number;
     /** Terminal typed-outcome reachability expressed as integer basis points. */
     terminal_outcome_reachability_basis_points: number;

package/dist/sdk/graph/governance.js

@@ -1,7 +1,8 @@
 
-!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]="b63fba34-8ca1-5e3a-905d-772ea8ce0f11")}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]="27de9c62-434c-566d-a000-54eddb9a16a9")}catch(e){}}();
 import { findRedundantRelationshipEdges, isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 import { findRelationshipCutStructure } from "./centrality.js";
+import { getWorkspaceHierarchyIntegrity } from "./assembly.js";
 import { RELATIONSHIP_AUDIT_FINDING_CODES, } from "./governance-contracts.js";
 /** Default bounded sample size applied to every finding family. */
 const DEFAULT_MAX_SAMPLE_SIZE = 25;
@@ -53,6 +54,48 @@ function buildFinding(code, severity, policy, describe, subjects, maxSampleSize,
             }),
     };
 }
+function collectHierarchyCycleFindings(analysis, maxSampleSize) {
+    return analysis.cycles.map((cycle) => buildFinding(cycle.legacy_terminal ? "legacy_hierarchy_cycle" : "hierarchy_cycle", cycle.legacy_terminal ? "info" : "error", "Structural hierarchy must be acyclic across scalar and registered dependency relationships.", (count) => `${count} items participate in one hierarchy cycle.`, cycle.item_ids, maxSampleSize, cycle.legacy_terminal
+        ? "Preserve historical rows unless an explicit legacy repair is approved."
+        : "Remove or retype one exact hierarchy relation before continuing mutation."));
+}
+function collectHierarchyCardinalityFindings(analysis, maxSampleSize, legacyTerminal) {
+    const rows = analysis.cardinality_violations.filter((finding) => finding.legacy_terminal === legacyTerminal);
+    if (rows.length === 0)
+        return [];
+    return [
+        buildFinding(legacyTerminal
+            ? "legacy_hierarchy_cardinality_violation"
+            : "hierarchy_cardinality_violation", legacyTerminal ? "info" : "error", "Every structural child must resolve to at most one logical parent across all hierarchy spellings.", (count) => `${count} child item${count === 1 ? "" : "s"} resolve to multiple hierarchy parents.`, rows.map((finding) => finding.child_id), maxSampleSize, legacyTerminal
+            ? "Preserve historical rows unless an explicit legacy repair is approved."
+            : "Remove the exact surplus hierarchy rows so each child has one parent.", rows.map((finding) => `${finding.child_id} <- ${finding.parent_ids.join(", ")}`)),
+    ];
+}
+function collectHierarchyDirectionFindings(analysis, maxSampleSize, legacyTerminal) {
+    const rows = analysis.divergences.filter((finding) => finding.legacy_terminal === legacyTerminal);
+    if (rows.length === 0)
+        return [];
+    return [
+        buildFinding(legacyTerminal
+            ? "legacy_hierarchy_direction_violation"
+            : "hierarchy_direction_violation", legacyTerminal ? "info" : "error", "Scalar parent metadata and dependency-backed hierarchy rows must resolve to the same logical parent.", (count) => `${count} child item${count === 1 ? "" : "s"} have divergent hierarchy storage surfaces.`, rows.map((finding) => finding.child_id), maxSampleSize, legacyTerminal
+            ? "Preserve historical rows unless an explicit legacy repair is approved."
+            : "Align the scalar parent and exact dependency rows to one canonical parent.", rows.map((finding) => `${finding.child_id}: scalar=${finding.scalar_parent_id} dependencies=${finding.dependency_parent_ids.join(",")}`)),
+    ];
+}
+/** Convert unified hierarchy analysis into lifecycle-aware governance findings. */
+function collectHierarchyIntegrityFindings(assembly, maxSampleSize) {
+    const analysis = getWorkspaceHierarchyIntegrity(assembly);
+    if (!analysis)
+        return [];
+    return [
+        ...collectHierarchyCycleFindings(analysis, maxSampleSize),
+        ...collectHierarchyCardinalityFindings(analysis, maxSampleSize, false),
+        ...collectHierarchyCardinalityFindings(analysis, maxSampleSize, true),
+        ...collectHierarchyDirectionFindings(analysis, maxSampleSize, false),
+        ...collectHierarchyDirectionFindings(analysis, maxSampleSize, true),
+    ];
+}
 /** Resolve the ordering-only successor adjacency for cycle analysis. */
 function buildOrderingAdjacency(assembly) {
     const registry = assembly.graph.registry();
@@ -336,23 +379,37 @@ function collectDuplicateRowFindings(assembly, maxSampleSize) {
 /** Build the reverse typed paths that can carry context toward an outcome. */
 function buildOutcomeReverseIndex(assembly, signal) {
     const reverse = new Map();
+    const basisKinds = {
+        source_to_target: [],
+        target_to_source: [],
+        both: [],
+    };
+    for (const definition of assembly.graph.registry().list()) {
+        if (definition.outcomeTraversal !== undefined) {
+            basisKinds[definition.outcomeTraversal].push(definition.kind);
+        }
+    }
+    const basis = {
+        source_to_target: basisKinds.source_to_target.join(","),
+        target_to_source: basisKinds.target_to_source.join(","),
+        both: basisKinds.both.join(","),
+    };
+    const append = (from, to) => {
+        const sources = reverse.get(to) ?? new Set();
+        sources.add(from);
+        reverse.set(to, sources);
+    };
     for (const edge of assembly.graph.edges()) {
         signal?.throwIfAborted();
         const definition = assembly.graph.registry().require(edge.kind);
-        let oriented;
-        if (definition.hierarchy) {
-            oriented = orientTransitiveEdge(edge, definition);
-        }
-        else if (definition.kind === "implements") {
-            oriented = { from: edge.source, to: edge.target };
-        }
-        if (oriented === undefined)
-            continue;
-        const sources = reverse.get(oriented.to) ?? new Set();
-        sources.add(oriented.from);
-        reverse.set(oriented.to, sources);
+        if (definition.outcomeTraversal === "source_to_target" ||
+            definition.outcomeTraversal === "both")
+            append(edge.source, edge.target);
+        if (definition.outcomeTraversal === "target_to_source" ||
+            definition.outcomeTraversal === "both")
+            append(edge.target, edge.source);
     }
-    return reverse;
+    return { basis, reverse };
 }
 /** Expand outcome nodes through every deterministic reverse typed path. */
 function expandOutcomeReachability(outcomes, reverse, signal) {
@@ -425,9 +482,11 @@ function profileOutcomeReachability(assembly, nodeStates, signal) {
             .toLowerCase()
             .startsWith(OUTCOME_MILESTONE_TITLE_PREFIX))
         .map((detail) => detail.id));
-    const reachable = expandOutcomeReachability(outcomes, buildOutcomeReverseIndex(assembly, signal), signal);
+    const { basis, reverse } = buildOutcomeReverseIndex(assembly, signal);
+    const reachable = expandOutcomeReachability(outcomes, reverse, signal);
     return {
         outcome_nodes: outcomes.size,
+        outcome_reachability_basis: basis,
         ...tallyOutcomeReachability(nodeStates, outcomes, reachable, signal),
     };
 }
@@ -561,6 +620,7 @@ export function auditWorkspaceRelationshipGraph(assembly, options = {}) {
     for (const edge of assembly.graph.edges())
         edgesByKind[edge.kind] = (edgesByKind[edge.kind] ?? 0) + 1;
     const findings = collectIntegrityFindings(assembly, isTerminal, maxSampleSize);
+    findings.push(...collectHierarchyIntegrityFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
     findings.push(...collectOrderingStorageContradictionFindings(assembly, maxSampleSize));
     options.signal?.throwIfAborted();
@@ -673,4 +733,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=b63fba34-8ca1-5e3a-905d-772ea8ce0f11
+//# debugId=27de9c62-434c-566d-a000-54eddb9a16a9