@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/sdk/governance/assurance.js

@@ -7,7 +7,7 @@
  * one deterministic SDK path.
  */
 
-!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]="2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb")}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]="d4c380ce-031e-5b2d-aaa8-658bb4aa3087")}catch(e){}}();
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { EXIT_CODE } from "../../core/shared/constants.js";
@@ -34,6 +34,7 @@ export const ASSURANCE_GATE_TRIGGERS = [
 export const ASSURANCE_MEASUREMENT_SOURCE_KINDS = [
     "items",
     "dependency_kind",
+    "prose_edge_gap",
     "graph",
     "validate",
     "health",
@@ -167,6 +168,53 @@ function validateItemsMeasurementSource(source) {
         throw new AssuranceMutationRefusalError("items source equals/state requires field");
     }
 }
+/** Validate relationship-provenance predicates on a dependency-kind measurement. */
+function validateDependencyKindMeasurementSource(source) {
+    if (typeof source.dependency_kind !== "string" ||
+        source.dependency_kind.trim().length === 0) {
+        throw new AssuranceMutationRefusalError("dependency_kind source requires dependency_kind");
+    }
+    const provenancePredicateCount = [
+        source.source_kind,
+        source.source_kind_prefix,
+        source.source_kind_state,
+    ].filter((value) => value !== undefined).length;
+    if (provenancePredicateCount > 1) {
+        throw new AssuranceMutationRefusalError("dependency_kind source accepts at most one source_kind predicate");
+    }
+    if ((source.source_kind !== undefined &&
+        source.source_kind.trim().length === 0) ||
+        (source.source_kind_prefix !== undefined &&
+            source.source_kind_prefix.trim().length === 0)) {
+        throw new AssuranceMutationRefusalError("dependency_kind source provenance values must not be empty");
+    }
+    if (source.source_kind_state !== undefined &&
+        source.source_kind_state !== "present" &&
+        source.source_kind_state !== "missing") {
+        throw new AssuranceMutationRefusalError("dependency_kind source source_kind_state must be present or missing");
+    }
+}
+/** Validate bounded, reasoned prose-parity exemptions. */
+function validateProseEdgeGapSource(source) {
+    if (source.sample_limit !== undefined &&
+        (!Number.isInteger(source.sample_limit) || source.sample_limit < 1)) {
+        throw new AssuranceMutationRefusalError("prose_edge_gap sample_limit must be a positive integer");
+    }
+    for (const exemption of source.exemptions ?? []) {
+        if (typeof exemption.holder_id !== "string" ||
+            exemption.holder_id.trim().length === 0 ||
+            typeof exemption.reason !== "string" ||
+            exemption.reason.trim().length === 0) {
+            throw new AssuranceMutationRefusalError("prose_edge_gap exemptions require holder_id and reason");
+        }
+        if ((exemption.target_id !== undefined &&
+            exemption.target_id.trim().length === 0) ||
+            (exemption.text_contains !== undefined &&
+                exemption.text_contains.trim().length === 0)) {
+            throw new AssuranceMutationRefusalError("prose_edge_gap exemption selectors must not be empty");
+        }
+    }
+}
 /** Validate and return one measurement declaration. */
 export function validateMeasurementDefinition(definition) {
     requireStableId(definition.id, "measurement.id");
@@ -185,11 +233,10 @@ export function validateMeasurementDefinition(definition) {
     if (source.kind === "items") {
         validateItemsMeasurementSource(source);
     }
-    if (source.kind === "dependency_kind" &&
-        (typeof source.dependency_kind !== "string" ||
-            source.dependency_kind.trim().length === 0)) {
-        throw new AssuranceMutationRefusalError("dependency_kind source requires dependency_kind");
-    }
+    if (source.kind === "dependency_kind")
+        validateDependencyKindMeasurementSource(source);
+    if (source.kind === "prose_edge_gap")
+        validateProseEdgeGapSource(source);
     if ((source.kind === "graph" ||
         source.kind === "validate" ||
         source.kind === "health") &&
@@ -419,6 +466,24 @@ function itemsSourceResult(source, context) {
         contributors: matches.map((item) => item.id),
     };
 }
+/** Match one normalized dependency provenance against an optional partition. */
+function dependencyProvenanceMatches(source, sourceKind) {
+    if (source.source_kind !== undefined) {
+        return (sourceKind?.toLowerCase() === source.source_kind.trim().toLowerCase());
+    }
+    if (source.source_kind_prefix !== undefined) {
+        return (sourceKind
+            ?.toLowerCase()
+            .startsWith(source.source_kind_prefix.trim().toLowerCase()) === true);
+    }
+    if (source.source_kind_state === "present") {
+        return sourceKind !== undefined && sourceKind.length > 0;
+    }
+    if (source.source_kind_state === "missing") {
+        return sourceKind === undefined || sourceKind.length === 0;
+    }
+    return true;
+}
 function dependencyKindSourceResult(source, context) {
     const contributors = [];
     const requestedKind = resolveCanonicalRelationshipKind(source.dependency_kind) ??
@@ -427,9 +492,10 @@ function dependencyKindSourceResult(source, context) {
         for (const dependency of item.dependencies ?? []) {
             const dependencyKind = resolveCanonicalRelationshipKind(dependency.kind) ??
                 dependency.kind.trim().toLowerCase();
-            if (dependencyKind === requestedKind) {
-                contributors.push(`${item.id}->${dependency.id}`);
-            }
+            const sourceKind = dependency.source_kind?.trim();
+            if (dependencyKind === requestedKind &&
+                dependencyProvenanceMatches(source, sourceKind))
+                contributors.push(`${item.id}->${dependency.id}${sourceKind ? `@${sourceKind}` : ""}`);
         }
     }
     return {
@@ -439,6 +505,109 @@ function dependencyKindSourceResult(source, context) {
         contributors,
     };
 }
+/** Return every text segment whose item identifiers form the prose graph. */
+function assuranceItemProseSegments(item) {
+    const segments = [item.description, item.body]
+        .filter((value) => typeof value === "string")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    for (const key of ["comments", "notes", "learnings"]) {
+        const entries = item[key];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (typeof entry === "string")
+                segments.push(entry);
+            else if (typeof entry === "object" && entry !== null) {
+                const text = Reflect.get(entry, "text");
+                if (typeof text === "string")
+                    segments.push(text);
+            }
+        }
+    }
+    return segments;
+}
+/** Return whether a reviewed exemption applies to one prose reference. */
+function proseReferenceIsExempt(exemptions, holderId, targetId, segment) {
+    return exemptions.some((exemption) => exemption.holder_id.trim().toLowerCase() === holderId.toLowerCase() &&
+        (exemption.target_id === undefined ||
+            exemption.target_id.trim().toLowerCase() === targetId.toLowerCase()) &&
+        (exemption.text_contains === undefined ||
+            segment
+                .toLowerCase()
+                .includes(exemption.text_contains.trim().toLowerCase())));
+}
+/** Return the direction-independent identity of a prose or structured item pair. */
+function prosePairKey(left, right) {
+    return [left.toLowerCase(), right.toLowerCase()].sort().join("\u0000");
+}
+/** Collect canonical ids, typed links, and raw prose mentions in one item pass. */
+function collectProseEdgeCensusInputs(items) {
+    const canonicalIds = new Map();
+    const linkedPairs = new Set();
+    const proseMentions = [];
+    const mentionPattern = /\b[a-z][a-z0-9]*-[a-z0-9]+\b/giu;
+    let mentionCount = 0;
+    for (const item of items) {
+        canonicalIds.set(item.id.toLowerCase(), item.id);
+        for (const dependency of item.dependencies ?? [])
+            linkedPairs.add(prosePairKey(item.id, dependency.id));
+        for (const scalar of [item.parent, item.blocked_by])
+            if (typeof scalar === "string")
+                linkedPairs.add(prosePairKey(item.id, scalar));
+        for (const segment of assuranceItemProseSegments(item)) {
+            const mentionedIds = [...segment.matchAll(mentionPattern)].map((match) => match[0]);
+            mentionCount += mentionedIds.length;
+            proseMentions.push({
+                holder_id: item.id,
+                segment,
+                mentioned_ids: mentionedIds,
+            });
+        }
+    }
+    return {
+        canonical_ids: canonicalIds,
+        linked_pairs: linkedPairs,
+        prose_mentions: proseMentions,
+        mention_count: mentionCount,
+    };
+}
+/** Count distinct prose-named item pairs that have no typed edge in either direction. */
+function proseEdgeGapSourceResult(source, context) {
+    const census = collectProseEdgeCensusInputs(context.items);
+    const gaps = new Map();
+    for (const proseMention of census.prose_mentions) {
+        const mentions = proseMention.mentioned_ids
+            .map((id) => census.canonical_ids.get(id.toLowerCase()))
+            .filter((id) => id !== undefined && id !== proseMention.holder_id);
+        const distinctMentions = [...new Set(mentions)];
+        for (const targetId of distinctMentions) {
+            const key = prosePairKey(proseMention.holder_id, targetId);
+            if (census.linked_pairs.has(key) ||
+                proseReferenceIsExempt(source.exemptions ?? [], proseMention.holder_id, targetId, proseMention.segment))
+                continue;
+            const explicit = distinctMentions.some((candidate) => candidate !== targetId);
+            if (gaps.get(key)?.explicit === true && !explicit)
+                continue;
+            gaps.set(key, {
+                contributor: `${proseMention.holder_id}->${targetId}|subject=${explicit ? "explicit" : "implicit"}`,
+                explicit,
+            });
+        }
+    }
+    const gapRows = [...gaps.values()];
+    const contributors = gapRows.map((entry) => entry.contributor).sort();
+    return {
+        value: contributors.length,
+        population_size: census.canonical_ids.size,
+        cost: context.items.length + census.linked_pairs.size + census.mention_count,
+        contributors: contributors.slice(0, source.sample_limit ?? 25),
+        partitions: {
+            explicit_subject: gapRows.filter((entry) => entry.explicit).length,
+            implicit_subject: gapRows.filter((entry) => !entry.explicit).length,
+        },
+    };
+}
 function historySourceResult(source, context) {
     const matches = context.history.filter((entry) => (source.op === undefined || entry.op === source.op) &&
         (source.author === undefined || entry.author === source.author) &&
@@ -471,6 +640,8 @@ function sourceResult(definition, context) {
     if (source.kind === "dependency_kind") {
         return dependencyKindSourceResult(source, context);
     }
+    if (source.kind === "prose_edge_gap")
+        return proseEdgeGapSourceResult(source, context);
     if (source.kind === "history")
         return historySourceResult(source, context);
     if (source.kind === "links")
@@ -583,6 +754,7 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
         units: result.cost,
         items_scanned: definition.source.kind === "items" ||
             definition.source.kind === "dependency_kind" ||
+            definition.source.kind === "prose_edge_gap" ||
             definition.source.kind === "links"
             ? context.items.length
             : 0,
@@ -603,6 +775,7 @@ async function evaluateMeasurementInternal(definition, context, definitions, sta
         population_size: result.population_size,
         cost,
         contributors: result.contributors ?? [],
+        ...(result.partitions ? { partitions: result.partitions } : {}),
     };
 }
 function evaluateMeasurementCached(definition, context, definitions, stack, state) {
@@ -670,6 +843,7 @@ export function evaluateAssuranceAssertion(definition, measurement, options = {}
         negative_control_proven: proveNegativeControl(definition),
         cost: measurement.cost,
         contributors: measurement.contributors,
+        ...(measurement.partitions ? { partitions: measurement.partitions } : {}),
     };
 }
 function enforceGateProviderPolicy(gate, document, context, trigger) {
@@ -1006,4 +1180,4 @@ export async function listAssuranceVerdicts(pmRoot, options = {}) {
         .slice(0, limit);
 }
 //# sourceMappingURL=assurance.js.map
-//# debugId=2bf52d6d-7e4f-5ec5-86bd-3e817ef521bb
+//# debugId=d4c380ce-031e-5b2d-aaa8-658bb4aa3087

package/dist/sdk/governance/gc.js

@@ -4,7 +4,8 @@
  * Implements the pm gc 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]="e982158e-4a8d-57a9-bd0b-24bd73aef342")}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]="76f8405f-138d-5119-a300-f068354394a5")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { runCheckpointGc } from "../../core/checkpoint/checkpoint-gc.js";
@@ -15,7 +16,7 @@ import { runLockGc } from "../../core/lock/lock-gc.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 const GC_SCOPE_VALUES = [
     "index",
@@ -234,9 +235,7 @@ function buildGcGuidance(params) {
 /** Implements run gc for the public runtime surface of this module. */
 export async function runGc(global, options = {}) {
     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 dryRun = options.dryRun === true;
     const scopes = parseScopes(options.scope);
@@ -367,4 +366,4 @@ export async function runGc(global, options = {}) {
     };
 }
 //# sourceMappingURL=gc.js.map
-//# debugId=e982158e-4a8d-57a9-bd0b-24bd73aef342
+//# debugId=76f8405f-138d-5119-a300-f068354394a5

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,14 @@
  * 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]="e7be701e-085c-5903-96da-61149452c673")}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 { isFileMissingError, pathExists, readFileIfExists, } from "../../core/fs/fs-utils.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";
 import { KNOWN_EXTENSION_CAPABILITIES, } from "../../core/extensions/loader.js";
@@ -43,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;
@@ -60,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:") ||
@@ -314,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
@@ -344,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}`,
@@ -359,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,
@@ -376,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
@@ -389,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,
@@ -1831,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,
@@ -1950,10 +1982,8 @@ function projectHealthResult(result, options, summaryMode) {
 /** Implements run health for the public runtime surface of this module. */
 export async function runHealth(global, options = {}) {
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
+    await assertInitializedTracker(pmRoot);
     const settingsPath = getSettingsPath(pmRoot);
-    if (!(await pathExists(settingsPath))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
     const { settings, warnings: settingsReadWarnings } = await readSettingsWithMetadata(pmRoot);
     const normalizedSettingsReadWarnings = [...new Set(settingsReadWarnings)];
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
@@ -2001,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);
@@ -2083,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,
@@ -2111,4 +2142,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=e7be701e-085c-5903-96da-61149452c673
+//# 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/reindex.js

@@ -4,10 +4,11 @@
  * Implements the pm reindex 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]="fc124f85-8d28-508b-a3f7-2fe767382197")}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]="1bcd20e1-2995-56ef-8d04-f265b8282c19")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { toNonEmptyStringOrUndefined, getActiveExtensionRegistrations, runActiveOnIndexHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, pathExists, writeFileAtomic, resolveItemTypeRegistry, parseItemDocument, acquireLock, buildSearchCorpus, buildSemanticCorpusInput, resolveSearchCorpusFields, resolveSemanticCorpusCharacterLimit, executeEmbeddingBatchesWithRetry, readVectorizationStatusLedger, writeVectorizationStatusLedger, REINDEX_LOCK_ID, resolveEmbeddingProviders, resolveSettingsWithSemanticRuntimeDefaults, executeVectorDelete, executeVectorReset, executeVectorUpsert, resolveVectorStores, buildVectorizationEmbeddingIdentity, buildVectorizationEmbeddingMetadata, hasVectorizationEmbeddingIdentityChanged, hasVectorizationVectorDimensionChanged, inferConsistentVectorDimension, EXIT_CODE, PmCliError, nowIso, listAllDocumentCandidatesCached, getSettingsPath, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
+import { toNonEmptyStringOrUndefined, getActiveExtensionRegistrations, runActiveOnIndexHooks, runActiveOnWriteHooks, collectRegisteredItemFieldNames, resolveRegisteredSearchProvider, resolveRegisteredVectorStoreAdapter, writeFileAtomic, resolveItemTypeRegistry, parseItemDocument, acquireLock, buildSearchCorpus, buildSemanticCorpusInput, resolveSearchCorpusFields, resolveSemanticCorpusCharacterLimit, executeEmbeddingBatchesWithRetry, readVectorizationStatusLedger, writeVectorizationStatusLedger, REINDEX_LOCK_ID, resolveEmbeddingProviders, resolveSettingsWithSemanticRuntimeDefaults, executeVectorDelete, executeVectorReset, executeVectorUpsert, resolveVectorStores, buildVectorizationEmbeddingIdentity, buildVectorizationEmbeddingMetadata, hasVectorizationEmbeddingIdentityChanged, hasVectorizationVectorDimensionChanged, inferConsistentVectorDimension, EXIT_CODE, PmCliError, nowIso, listAllDocumentCandidatesCached, resolvePmRoot, readSettings, resolveAuthor, } from "../runtime-primitives.js";
 const MANIFEST_PATH = "index/manifest.json";
 const EMBEDDINGS_PATH = "search/embeddings.jsonl";
 const EMBEDDING_MIGRATION_REINDEX_HINT = "Provider or model has changed since last index. Run pm reindex --mode semantic to rebuild.";
@@ -630,9 +631,7 @@ export async function runReindex(options, global) {
     const forceFullSemantic = options.full === true;
     emitReindexProgress(progressEnabled, `start mode=${requestedMode}`);
     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 = resolveSettingsWithSemanticRuntimeDefaults(await readSettings(pmRoot)).settings;
     let releaseReindexLock = null;
     try {
@@ -760,4 +759,4 @@ export async function runReindex(options, global) {
     }
 }
 //# sourceMappingURL=reindex.js.map
-//# debugId=fc124f85-8d28-508b-a3f7-2fe767382197
+//# debugId=1bcd20e1-2995-56ef-8d04-f265b8282c19