@unbrained/pm-cli 2026.8.19 → 2026.8.21

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.js

@@ -4,11 +4,12 @@
  * 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]="a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
-import { isFileMissingError, pathExists, readFileIfExists, } from "../../core/fs/fs-utils.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";
@@ -1950,10 +1951,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());
@@ -2111,4 +2110,4 @@ export const _testOnlyHealthCommand = {
     warningCode,
 };
 //# sourceMappingURL=health.js.map
-//# debugId=e7be701e-085c-5903-96da-61149452c673
+//# debugId=a7e3a41b-7d69-526d-aa3e-bc244ef8fe0c

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

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

@@ -13,8 +13,7 @@ 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. */

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]="1ed6b663-882a-5936-bd89-46bbbb17d806")}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";
@@ -78,11 +79,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",
@@ -2226,9 +2222,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 +2307,4 @@ export async function runValidate(options, global, services = {}) {
 }
 /* c8 ignore stop */
 //# sourceMappingURL=validate.js.map
-//# debugId=b8c4707f-5445-5079-96e5-dc0dbd649b34
+//# debugId=1ed6b663-882a-5936-bd89-46bbbb17d806

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,5 +1,5 @@
 
-!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]="c5dbaccd-d0e5-5511-b659-4f0a5f45ccaf")}catch(e){}}();
 import { findRedundantRelationshipEdges, isTransitiveKind, orientTransitiveEdge, transitiveFamilyKey, } from "./analytics.js";
 import { findRelationshipCutStructure } from "./centrality.js";
 import { RELATIONSHIP_AUDIT_FINDING_CODES, } from "./governance-contracts.js";
@@ -336,23 +336,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 +439,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),
     };
 }
@@ -673,4 +689,4 @@ export function diffRelationshipAuditSnapshots(baseline, current) {
     };
 }
 //# sourceMappingURL=governance.js.map
-//# debugId=b63fba34-8ca1-5e3a-905d-772ea8ce0f11
+//# debugId=c5dbaccd-d0e5-5511-b659-4f0a5f45ccaf

package/dist/sdk/graph/run.js

@@ -11,9 +11,9 @@
  * queries in long-lived hosts are answered from the memoized snapshot.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6c8bfb7a-687a-5fbb-b408-ffdbab1187a9")}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]="b7aa5929-ab87-5616-a749-1c353ae7b3c3")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { isTerminalStatus } from "../../core/item/status.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry } from "../../core/schema/runtime-schema.js";
@@ -21,7 +21,7 @@ import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { createUnknownSubcommandError } from "../agent/subcommand-recovery.js";
 import { listAllItemMetadataLight } from "../../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../../core/store/paths.js";
+import { resolvePmRoot } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { parseDirection, parseKinds, parseMaxDepth, parsePositiveInteger, } from "../dependencies.js";
 import { analyzeGraphImpact, analyzeKnowledgeGraph, analyzeRelationshipExecution, } from "../relationship-analytics.js";
@@ -661,9 +661,7 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     const subcommand = parseGraphSubcommand(subcommandRaw, id, target);
     assertProjectionModeChoice(options.summary === true, options.full === true, "--summary");
     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 typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const items = await listAllItemMetadataLight(pmRoot, settings.item_format, typeRegistry.type_to_folder, undefined, settings.schema);
@@ -719,4 +717,4 @@ export async function runGraph(subcommandRaw, id, target, options, global) {
     return attachGraphProjection(value, invocation.summary, "result_rows");
 }
 //# sourceMappingURL=run.js.map
-//# debugId=6c8bfb7a-687a-5fbb-b408-ffdbab1187a9
+//# debugId=b7aa5929-ab87-5616-a749-1c353ae7b3c3

package/dist/sdk/graph/traversal.js

@@ -1,6 +1,6 @@
 /** Default number of paths returned by bounded path enumeration. */
 
-!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]="c0fb747e-1f9f-55c4-808b-b77d3a881f87")}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]="ac2b3cd9-5a98-5fea-888c-e96de8cd593d")}catch(e){}}();
 const DEFAULT_MAX_PATHS = 5;
 /** Default expansion-safety bound for bounded path enumeration. */
 const DEFAULT_MAX_VISITED_PATHS = 10_000;
@@ -50,8 +50,17 @@ function resolveFamilyKinds(graph, kinds, family) {
     const resolved = new Set();
     for (const kind of kinds) {
         const definition = registry.require(kind);
-        if (!definition[family])
-            throw new TypeError(`Relationship kind ${definition.kind} is not a ${family} kind`);
+        // Registry registration normalizes this optional compatibility field before
+        // definitions become queryable.
+        const traversal = definition.traversal;
+        if (traversal === "association")
+            throw new TypeError(`Relationship kind ${definition.kind} uses association traversal; use graph impact --direction both`);
+        if (traversal !== family && traversal !== "semantic") {
+            const redirect = traversal === "hierarchy"
+                ? "graph ancestors or graph descendants"
+                : "graph predecessors or graph successors";
+            throw new TypeError(`Relationship kind ${definition.kind} uses ${traversal} traversal; use ${redirect}`);
+        }
         resolved.add(definition.kind);
     }
     return resolved;
@@ -67,7 +76,7 @@ function expandSemanticNeighbors(graph, nodeId, familyKinds, family, matches) {
     const seen = new Set();
     for (const row of rows.value) {
         const definition = registry.require(row.edge.kind);
-        if (!definition[family])
+        if (familyKinds === undefined && !definition[family])
             continue;
         if (!matches(row, definition, nodeId))
             continue;
@@ -273,4 +282,4 @@ export function enumerateRelationshipPaths(graph, source, target, options = {})
     return enumerateNonZeroRelationshipPaths(graph, source, target, options, maxPaths, maxVisitedPaths, maxDepth, direction);
 }
 //# sourceMappingURL=traversal.js.map
-//# debugId=c0fb747e-1f9f-55c4-808b-b77d3a881f87
+//# debugId=ac2b3cd9-5a98-5fea-888c-e96de8cd593d