@unbrained/pm-cli 2026.8.20 → 2026.8.21

package/dist/sdk/query/search.js

@@ -4,7 +4,8 @@
  * Implements the pm search 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]="c650f22f-5fcd-5489-aa9b-da11c2d1db63")}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]="a4117e19-af3e-50f5-b3cc-86c39aa4b439")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { toNonEmptyStringOrUndefined } from "../../core/shared/primitives.js";
@@ -23,7 +24,6 @@ import { readVectorizationStatusLedger } from "../../core/search/cache.js";
 import { buildEventCorpus, buildPlanFlatCorpus, buildReminderCorpus, buildSearchCorpus, resolveSearchCorpusFields, } from "../../core/search/corpus.js";
 import { buildBm25Index, flattenSearchCorpusText, resolveBm25Params, scoreBm25Query, tokenizeBm25, } from "../../core/search/bm25.js";
 import { collectStaleVectorizationIds } from "../../core/search/staleness.js";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { parseItemDocument } from "../../core/item/item-format.js";
 import { toItemRecord } from "../../core/item/item-record.js";
 import { isTerminalStatus } from "../../core/item/status.js";
@@ -40,7 +40,7 @@ import { tokenizeAlphaNumeric } from "../../core/shared/text-normalization.js";
 import { compareTimestampStrings, matchesTimestampFilters, nowIso, } from "../../core/shared/time.js";
 import { listAllDocumentCandidatesCached } from "../../core/store/item-metadata-cache.js";
 import { listAllItemMetadata } from "../../core/store/item-store.js";
-import { getItemPath, getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { getItemPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { resolveSearchPage } from "./search-pagination.js";
 import { normalizeSearchPhrase, parseMinScoreOverride, parseSearchBoolean, parseSearchDeadline, parseSearchMatchMode, parseSearchMode, parseSearchProjection, parseSearchTokens, parseSemanticWeightOverride, parseTimestampWindow, resolveHybridSemanticWeight, resolveSearchMaxResults, resolveSearchScoreThreshold, resolveSearchTuning, validateSearchProjectionFields, } from "./search-contracts.js";
@@ -1571,9 +1571,7 @@ function prepareSearchInput(rawQuery, rawOptions) {
 }
 async function resolveSearchRuntimeContext(prepared, global) {
     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 storedSettings = await readSettings(pmRoot);
     const settings = resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;
     const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
@@ -1987,4 +1985,4 @@ export async function runSearch(rawQuery, rawOptions, global) {
     return withSearchWorkspaceMemory(buildSearchResultForHits(response, projectedItems, total, page.limited.length, effectiveProjection, page.pageExtras), workspaceMemoryResult);
 }
 //# sourceMappingURL=search.js.map
-//# debugId=c650f22f-5fcd-5489-aa9b-da11c2d1db63
+//# debugId=a4117e19-af3e-50f5-b3cc-86c39aa4b439

package/dist/sdk/relationship-kinds/contract.d.ts

@@ -15,12 +15,20 @@ export type RelationshipTemporalOrder = "source_after_target";
 export type RelationshipPrecedence = "source_before_target" | "target_before_source";
 /** Endpoint that represents the structural parent for hierarchy kinds. */
 export type RelationshipHierarchyDirection = "source_parent" | "target_parent";
+/** Closure family that gives a relationship its default traversal vocabulary. */
+export type RelationshipTraversalFamily = "hierarchy" | "ordering" | "semantic" | "association";
+/** Direction in which an edge can carry a node toward a declared outcome. */
+export type RelationshipOutcomeTraversal = "source_to_target" | "target_to_source" | "both";
 /** Versioned semantic definition for a built-in or application-defined edge kind. */
 export interface RelationshipKindDefinition {
     /** Canonical, case-insensitive kind identifier. */
     kind: string;
     /** Whether traversing source to target has distinct meaning from the reverse. */
     direction: RelationshipDirection;
+    /** Default closure vocabulary; omitted custom definitions infer it from legacy flags. */
+    traversal?: RelationshipTraversalFamily;
+    /** Direction this kind contributes to typed outcome reachability, when any. */
+    outcomeTraversal?: RelationshipOutcomeTraversal;
     /** Optional canonical kind used when traversing a directed edge in reverse. */
     inverse?: string;
     /** Whether the kind participates in execution-order cycle checks. */

package/dist/sdk/relationship-kinds/contract.js

@@ -5,19 +5,19 @@
  */
 /** Stable built-in relationship ontology without graph or storage dependencies. */
 
-!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]="825e1dd9-4168-56f6-9183-b8cf75314b73")}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]="aa7d04c7-b057-569c-816a-f53322c74261")}catch(e){}}();
 export const BUILTIN_RELATIONSHIP_KINDS = [
-    { kind: "blocked_by", direction: "directed", inverse: "blocks", ordering: true, precedence: "target_before_source", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["depends_on"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "blocks", direction: "directed", inverse: "blocked_by", ordering: true, precedence: "source_before_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "parent", direction: "directed", inverse: "child", ordering: false, hierarchy: true, hierarchyDirection: "target_parent", outgoing: "one", incoming: "many", lifecycle: "supersedable", aliases: ["child_of", "epic"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "child", direction: "directed", inverse: "parent", ordering: false, hierarchy: true, hierarchyDirection: "source_parent", outgoing: "many", incoming: "one", lifecycle: "supersedable", aliases: ["parent_child", "task"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "related", direction: "undirected", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["related_to"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "discovered_from", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "incident_from", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "implements", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "recurs_from", direction: "directed", ordering: false, temporalOrder: "source_after_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "verifies", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "supersedes", direction: "directed", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "supersedable", compatibilityVersion: 1, allowSelf: false },
+    { kind: "blocked_by", direction: "directed", traversal: "ordering", inverse: "blocks", ordering: true, precedence: "target_before_source", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["depends_on"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "blocks", direction: "directed", traversal: "ordering", inverse: "blocked_by", ordering: true, precedence: "source_before_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "parent", direction: "directed", traversal: "hierarchy", outcomeTraversal: "source_to_target", inverse: "child", ordering: false, hierarchy: true, hierarchyDirection: "target_parent", outgoing: "one", incoming: "many", lifecycle: "supersedable", aliases: ["child_of", "epic"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "child", direction: "directed", traversal: "hierarchy", outcomeTraversal: "target_to_source", inverse: "parent", ordering: false, hierarchy: true, hierarchyDirection: "source_parent", outgoing: "many", incoming: "one", lifecycle: "supersedable", aliases: ["parent_child", "task"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "related", direction: "undirected", traversal: "association", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["related_to"], compatibilityVersion: 1, allowSelf: false },
+    { kind: "discovered_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "incident_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "implements", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "recurs_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, temporalOrder: "source_after_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "verifies", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
+    { kind: "supersedes", direction: "directed", traversal: "semantic", outcomeTraversal: "both", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "supersedable", compatibilityVersion: 1, allowSelf: false },
 ];
 //# sourceMappingURL=contract.js.map
-//# debugId=825e1dd9-4168-56f6-9183-b8cf75314b73
+//# debugId=aa7d04c7-b057-569c-816a-f53322c74261

package/dist/sdk/relationships.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Dependency, ItemMetadata } from "../types/index.js";
 import { type RelationshipKindDefinition } from "./relationship-kinds/contract.js";
-export { BUILTIN_RELATIONSHIP_KINDS, type RelationshipCardinality, type RelationshipDirection, type RelationshipHierarchyDirection, type RelationshipKindDefinition, type RelationshipLifecycle, type RelationshipPrecedence, type RelationshipTemporalOrder, } from "./relationship-kinds/contract.js";
+export { BUILTIN_RELATIONSHIP_KINDS, type RelationshipCardinality, type RelationshipDirection, type RelationshipHierarchyDirection, type RelationshipKindDefinition, type RelationshipLifecycle, type RelationshipOutcomeTraversal, type RelationshipPrecedence, type RelationshipTemporalOrder, type RelationshipTraversalFamily, } from "./relationship-kinds/contract.js";
 /** One normalized relationship edge indexed by the graph kernel. */
 export interface RelationshipEdge {
     /** Source node identifier. */

package/dist/sdk/relationships.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]="7f733de4-104b-50a9-9c0a-cd9850bfcd78")}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]="b1c32b57-0231-5bea-ade4-99247504f938")}catch(e){}}();
 import { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 export { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 function normalizeKind(kind) {
@@ -82,6 +82,16 @@ function assertRelationshipKindSemantics(definition, kind) {
         throw new TypeError(`Invalid relationship lifecycle for ${kind}`);
     if (typeof definition.allowSelf !== "boolean")
         throw new TypeError(`Invalid relationship self-edge flag for ${kind}`);
+    if (definition.traversal !== undefined &&
+        !["hierarchy", "ordering", "semantic", "association"].includes(definition.traversal))
+        throw new TypeError(`Invalid relationship traversal family for ${kind}`);
+    if (definition.outcomeTraversal !== undefined &&
+        !["source_to_target", "target_to_source", "both"].includes(definition.outcomeTraversal))
+        throw new TypeError(`Invalid outcome traversal for ${kind}`);
+    if (definition.direction === "undirected" &&
+        definition.outcomeTraversal !== undefined &&
+        definition.outcomeTraversal !== "both")
+        throw new TypeError(`Undirected relationship kind cannot declare directional outcome traversal: ${kind}`);
 }
 /** Validate application payload-schema and compatibility-alias containers. */
 function assertRelationshipKindPayload(definition, kind) {
@@ -129,6 +139,14 @@ export class RelationshipKindRegistry {
         const normalized = Object.freeze({
             ...definition,
             kind,
+            traversal: definition.traversal ??
+                (definition.hierarchy
+                    ? "hierarchy"
+                    : definition.ordering
+                        ? "ordering"
+                        : definition.direction === "undirected"
+                            ? "association"
+                            : "semantic"),
             hierarchy: definition.hierarchy ?? false,
             inverse,
             aliases: Object.freeze(aliases),
@@ -552,4 +570,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=7f733de4-104b-50a9-9c0a-cd9850bfcd78
+//# debugId=b1c32b57-0231-5bea-ade4-99247504f938

package/dist/sdk/schema-migration.js

@@ -7,11 +7,12 @@
  * guarantees.
  */
 
-!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]="cd777de3-665f-5e01-ac98-8986f2a5a4c2")}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]="60738c1f-3b44-5f8a-82c9-99d2b2de1e51")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { isFileMissingError, pathExists, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
+import { isFileMissingError, readFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
 import { appendWorkspaceHistoryChange } from "../core/history/workspace-history.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { parseFieldsFile, serializeFieldsFile, } from "../core/schema/fields-file.js";
@@ -21,7 +22,7 @@ import { parseStatusDefsFile, serializeStatusDefsFile, } from "../core/schema/st
 import { normalizeStatusToken } from "../core/schema/status-token.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { listAllItemMetadataLight, locateItem, mutateItem, readLocatedItem, } 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 { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
@@ -725,9 +726,7 @@ async function appendSchemaReferenceHistory(params) {
 export async function runSchemaEvolutionMigration(requestInput, options, global) {
     const request = normalizedRequest(requestInput);
     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 migrationId = options.migrationId === undefined
         ? deriveSchemaEvolutionMigrationId(request, await fs.realpath(pmRoot))
         : requiredMigrationId(options.migrationId);
@@ -855,4 +854,4 @@ export const schemaMigrationTestOnly = {
     validateAndStoreMigrationPlan,
 };
 //# sourceMappingURL=schema-migration.js.map
-//# debugId=cd777de3-665f-5e01-ac98-8986f2a5a4c2
+//# debugId=60738c1f-3b44-5f8a-82c9-99d2b2de1e51

package/dist/sdk/schema.js

@@ -4,7 +4,8 @@
  * Owns typed schema customization primitives shared by SDK, CLI, and MCP consumers.
  */
 
-!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]="2ab8a5a9-dbea-526f-a541-b7ca2b106ac5")}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]="6112923d-5e06-5839-b452-a32818c6398d")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -24,7 +25,7 @@ import { EXIT_CODE } from "../core/shared/constants.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
 import { getActiveExtensionRegistrations, runActiveOnWriteHooks, } from "../core/extensions/index.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings, resolveGovernanceKnobs, } from "../core/store/settings.js";
 import { resolvePmToolCustomFieldCollision } from "./cli-contracts/tool-schema.js";
 /** Public contract for schema subcommands, shared by SDK and presentation-layer consumers. */
@@ -160,9 +161,7 @@ export async function runSchemaAddType(name, options, global) {
     };
 }
 async function ensureInitialized(pmRoot) {
-    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);
 }
 /**
  * Reconcile the committed merge-driver fence with the type folders that exist
@@ -1365,4 +1364,4 @@ export const _testOnlySchemaCommand = {
     workflowSlotsReferencing,
 };
 //# sourceMappingURL=schema.js.map
-//# debugId=2ab8a5a9-dbea-526f-a541-b7ca2b106ac5
+//# debugId=6112923d-5e06-5839-b452-a32818c6398d

package/dist/sdk/stats.js

@@ -4,7 +4,8 @@
  * Implements the pm stats 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]="d28c7ac7-9801-5b0c-84c9-51deede398be")}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]="b56db1fc-d989-5d18-8b29-336a03f1e525")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { getActiveExtensionRegistrations, runActiveOnReadHooks, } from "../core/extensions/index.js";
@@ -15,11 +16,9 @@ import { enforceHistoryStreamPolicyForItems } from "../core/history/history-stre
 import { computeHistoryStorageStats, } from "../core/history/history-storage-stats.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
 import { nowIso } from "../core/shared/time.js";
 import { listAllItemMetadataLight, listAllItemMetadataWithBody, } 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 { recordImprovementObservation, readImprovementLedger, } from "./improvement-ledger.js";
 import { projectFleetAttributionAnalytics, projectProvenanceCoverageAnalytics, readHistoryAnalyticsWindow, } from "./history-analytics.js";
@@ -210,9 +209,7 @@ function assembleStatsResult(totals, byType, byStatus, omittedZeroBuckets, optio
 /** Implements run stats for the public runtime surface of this module. */
 export async function runStats(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 recordedObservations = await recordStatsObservations(global, options);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
@@ -271,4 +268,4 @@ export async function runStats(global, options = {}) {
     });
 }
 //# sourceMappingURL=stats.js.map
-//# debugId=d28c7ac7-9801-5b0c-84c9-51deede398be
+//# debugId=b56db1fc-d989-5d18-8b29-336a03f1e525

package/dist/sdk/templates.js

@@ -4,7 +4,8 @@
  * Implements the pm templates 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]="f232e106-54f4-572e-8f6e-054f52290267")}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]="5c70da27-21f6-5d31-b506-96e1818996d6")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathExists, readFileIfExists, } from "../core/fs/fs-utils.js";
@@ -13,7 +14,7 @@ import { resolveAuthor } from "../core/shared/author.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";
 import { CREATE_COMMANDER_REPEATABLE_OPTION_CONTRACTS } from "./cli-contracts.js";
 const TEMPLATE_DIRECTORY_NAME = "templates";
@@ -78,9 +79,7 @@ function templatePath(pmRoot, normalizedName) {
     return path.join(templatesDirectory(pmRoot), `${normalizedName}${TEMPLATE_FILE_EXTENSION}`);
 }
 async function ensureTrackerInitialized(pmRoot) {
-    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);
 }
 function sortTemplateOptions(options) {
     return Object.fromEntries(Object.entries(options).sort(([left], [right]) => left.localeCompare(right)));
@@ -291,4 +290,4 @@ export async function runTemplatesShow(rawTemplateName, global) {
     };
 }
 //# sourceMappingURL=templates.js.map
-//# debugId=f232e106-54f4-572e-8f6e-054f52290267
+//# debugId=5c70da27-21f6-5d31-b506-96e1818996d6

package/dist/sdk/test/batch.js

@@ -4,8 +4,8 @@
  * Implements the pm test all 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]="7fea0ecb-35e2-5d40-931f-ffdd1a465fdc")}catch(e){}}();
-import { pathExists } from "../../core/fs/fs-utils.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]="aeb0a1a7-bc73-5c56-bbed-9472c651b5f6")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { getActiveExtensionRegistrations } from "../../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../../core/item/type-registry.js";
 import { parseOptionalNumber } from "../../core/item/parse.js";
@@ -15,7 +15,7 @@ import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { nowIso } from "../../core/shared/time.js";
 import { listAllItemMetadataLight } from "../../core/store/item-store.js";
-import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { appendTrackedTestRunSummary } from "../../core/test/item-test-run-tracking.js";
 import { resolveAuthor } from "../../core/shared/author.js";
@@ -421,9 +421,7 @@ const buildTestAllSelectionProgress = (params) => [
 /** Loads the tracker selection and linked tests for one test-all run. */
 const prepareTestAllRun = async (options, global) => {
     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 selection = await selectTestAllItems({ pmRoot, settings, options });
     const defaultTimeoutSeconds = parseTimeout(options.timeout);
@@ -489,4 +487,4 @@ export const _testOnlyTestAll = {
     formatTrackingError,
 };
 //# sourceMappingURL=batch.js.map
-//# debugId=7fea0ecb-35e2-5d40-931f-ffdd1a465fdc
+//# debugId=aeb0a1a7-bc73-5c56-bbed-9472c651b5f6

package/dist/sdk/test/execution.js

@@ -4,7 +4,8 @@
  * Implements the pm test 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]="4322c352-6b95-5796-94eb-5a68745d53bc")}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]="2354c553-3a81-59d8-9c0a-3d19cd3cedd2")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -1849,9 +1850,7 @@ function buildTestMeasurementProjection(options, runs, recordedRun) {
 export async function runTest(id, options, global) {
     const stdinResolver = createStdinTokenResolver();
     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);
     if ((options.measure?.length ?? 0) > 0 && options.run !== true) {
         throw new PmCliError("--measure requires --run", EXIT_CODE.USAGE);
@@ -1965,4 +1964,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=4322c352-6b95-5796-94eb-5a68745d53bc
+//# debugId=2354c553-3a81-59d8-9c0a-3d19cd3cedd2

package/dist/sdk/test/runs.js

@@ -4,14 +4,14 @@
  * Implements the pm test runs 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]="8f02f498-5cee-59fa-9f4e-fd882c58d401")}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]="1cbb3565-26d8-5657-b724-602658bec852")}catch(e){}}();
+import { assertInitializedTracker } from "../environment/tracker-preflight.js";
 import os from "node:os";
-import { pathExists } from "../../core/fs/fs-utils.js";
 import { EXIT_CODE } from "../../core/shared/constants.js";
 import { PmCliError } from "../../core/shared/errors.js";
 import { readAuthorEnvironment } from "../../core/shared/author.js";
 import { getBackgroundTestRunStatus, listBackgroundTestRuns, readBackgroundTestRunLogs, resumeBackgroundTestRun, runBackgroundTestRunWorker, spawnBackgroundTestRunWorker, startBackgroundTestRun, stopBackgroundTestRun, } from "../../core/test/background-runs.js";
-import { getSettingsPath, resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
+import { resolveGlobalPmRoot, resolvePmRoot, } from "../../core/store/paths.js";
 import { readSettings } from "../../core/store/settings.js";
 import { parseLimit } from "../../core/shared/numeric-parsers.js";
 const BACKGROUND_STATUS_VALUES = [
@@ -81,9 +81,7 @@ function resolveRequestedBy(author, fallback) {
     return "unknown";
 }
 async function ensureInitialized(pmRoot) {
-    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);
 }
 /** Implements run start background run for the public runtime surface of this module. */
 export async function runStartBackgroundRun(options, global) {
@@ -193,4 +191,4 @@ export async function runTestRunsWorker(runId, global) {
     };
 }
 //# sourceMappingURL=runs.js.map
-//# debugId=8f02f498-5cee-59fa-9f4e-fd882c58d401
+//# debugId=1cbb3565-26d8-5657-b724-602658bec852

package/docs/AGENT_UX_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Agent UX Contracts
 
-Tracker references: [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon).
+Tracker references: [pm-v1yo](../.agents/pm/issues/pm-v1yo.toon), [pm-i6pi](../.agents/pm/issues/pm-i6pi.toon), [pm-um4g](../.agents/pm/issues/pm-um4g.toon), [pm-tmhs](../.agents/pm/issues/pm-tmhs.toon), [pm-6m1i](../.agents/pm/issues/pm-6m1i.toon), [pm-cj9v](../.agents/pm/issues/pm-cj9v.toon), [pm-yp56](../.agents/pm/issues/pm-yp56.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), and [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon).
 
 These contracts keep common agent loops deterministic, token-efficient, and recoverable. Runtime contracts and `--help --json` remain the exact source for available flags.
 
@@ -10,6 +10,13 @@ These contracts keep common agent loops deterministic, token-efficient, and reco
 
 The public SDK exports `collectNewOrderingCycleWarnings(beforeItems, afterItems, changedItemId)` from `@unbrained/pm-cli/sdk`. Package authors can apply the same immutable-snapshot advisory to custom mutation workflows; activated custom relationship kinds participate through the shared registry.
 
+Dependency removal is lossless. `--dep-remove` rejects the same malformed
+shorthand as `--dep`, and a selector that matches nothing returns the typed
+`dependency_remove_no_match` refusal instead of a successful no-op. Exact
+duplicate rows can be normalized without delete-then-add risk by re-adding the
+same `id`, `kind`, and `source_kind`; the mutation keeps one canonical row and
+never removes the logical edge.
+
 `pm graph audit` uses two explicit units:
 
 - `finding_count`, `findings_by_severity`, and `findings_by_code` count finding rows.

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -1,6 +1,6 @@
 # Dependency-kind contract
 
-Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon)
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), and [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon).
 
 Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
 
@@ -15,6 +15,17 @@ Dependency rows have one canonical stored spelling per relationship meaning. Com
 
 The SDK relationship registry is authoritative. `canonicalizeRelationshipKind()` rejects unknown spellings, while `resolveCanonicalRelationshipKind()` supports validation flows that need an undefined result. `pm contracts` publishes `relationship_kind_contracts` with canonical names, aliases, inverses, and ordering/hierarchy semantics.
 
+Dependency additions and removals share the same lossless input grammar. A
+bare value is an item id; structured input uses `id=<id>` plus an optional
+canonical `kind`/`type` and `source_kind`. Punctuation-shaped shorthand such as
+`OTHER,related` is rejected with `dependency_flag_value_invalid` on both
+`--dep` and `--dep-remove`, before prefix normalization can turn it into a
+dangling id. A removal selector that matches no stored row fails with
+`dependency_remove_no_match` and returns the unmatched selectors plus compact
+available identities. Re-adding a stored dependency identity is idempotent; if
+legacy storage contains that exact identity more than once, the same mutation
+collapses the touched copies to one without creating an edge-absence window.
+
 `recurs_from` has no alias: a later occurrence points to an earlier occurrence.
 It is persistent after both items become terminal and carries temporal identity,
 not execution precedence. `supersedes` keeps replacement semantics, while

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -65,6 +65,43 @@ Generic action hosts use `item-reopen` with required `id` and `reason` fields.
 The action participates in the generated action schema, SDK dispatch coverage,
 CLI/SDK parameter parity, command grammar, and MCP `pm_run` surface.
 
+## Tracker Preflight Recovery
+
+Every SDK command that requires project state now enters through one shared
+filesystem preflight instead of maintaining a command-local settings check.
+The public aggregate SDK exposes the same primitive for packages and embedded
+hosts:
+
+```ts
+import {
+  assertInitializedTracker,
+  assertReadableTrackerRoot,
+} from "@unbrained/pm-cli/sdk";
+
+await assertReadableTrackerRoot(candidateRoot); // an empty directory is valid
+await assertInitializedTracker(projectRoot); // settings.json is required
+```
+
+The refusal contract distinguishes four states before any command-specific
+read or mutation begins:
+
+| Selected root state | Code | Exit | Recovery |
+| --- | --- | ---: | --- |
+| Path does not exist | `tracker_root_missing` | 3 | Tokenized, non-interactive `pm --pm-path <path> init --defaults --agent-guidance skip` |
+| Directory exists but `settings.json` does not | `tracker_not_initialized` | 3 | The same initialization retry |
+| Path or ancestor is a regular file | `tracker_root_not_directory` | 2 | Select a directory; never suggest `pm init` against the file |
+| Directory cannot be read or searched | `tracker_root_unreadable` | 1 | Repair permissions, then retry the same selected root |
+
+`listTrackerPreflightRecoveryContracts` publishes this four-state corpus from
+`@unbrained/pm-cli/sdk/contracts`.
+`scoreTrackerPreflightRecoveryClosure` verifies code, exit class, recovery kind,
+and executable retry evidence. The repository recovery gate runs these probes
+beside the 18 closed-domain probes, so its ratcheted corpus is 22 and a removed
+state, failed retry, or unsafe file-path initialization suggestion blocks the
+release. The surface-replication gate separately requires at least 50 shared
+preflight invocations across the 45 migrated SDK modules and forbids the former
+inline error body from returning.
+
 ## Duplicate Intake
 
 Create and copy similarity governance inspect all lifecycle statuses. The