@unbrained/pm-cli 2026.8.20 → 2026.8.22

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]="d7d44fba-603b-5ef2-8490-51112b929433")}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) {
@@ -95,6 +105,17 @@ function assertRelationshipKindPayload(definition, kind) {
             definition.aliases.some((alias) => typeof alias !== "string")))
         throw new TypeError(`Invalid relationship aliases for ${kind}`);
 }
+function resolveRelationshipTraversal(definition) {
+    if (definition.traversal)
+        return definition.traversal;
+    // Dual-family extension kinds use ordering precedence, matching relationship
+    // context role classification. Explicit traversal always remains authoritative.
+    if (definition.ordering)
+        return "ordering";
+    if (definition.hierarchy)
+        return "hierarchy";
+    return definition.direction === "undirected" ? "association" : "semantic";
+}
 /** Mutable registry with immutable snapshots and collision-safe extension registration. */
 export class RelationshipKindRegistry {
     #definitions = new Map();
@@ -129,7 +150,11 @@ export class RelationshipKindRegistry {
         const normalized = Object.freeze({
             ...definition,
             kind,
+            traversal: resolveRelationshipTraversal(definition),
             hierarchy: definition.hierarchy ?? false,
+            hierarchyDirection: definition.hierarchy
+                ? (definition.hierarchyDirection ?? "source_parent")
+                : undefined,
             inverse,
             aliases: Object.freeze(aliases),
             payloadSchema: definition.payloadSchema
@@ -552,4 +577,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=7f733de4-104b-50a9-9c0a-cd9850bfcd78
+//# debugId=d7d44fba-603b-5ef2-8490-51112b929433

package/dist/sdk/runtime.d.ts

@@ -6,6 +6,7 @@
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, type EnsurePmGitignoreResult, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
 export type { FlagDefinition } from "../core/extensions/loader.js";
+export * from "./cli-contracts/agent-output-contracts.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import type { ItemMetadata } from "../types/index.js";
 import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
@@ -155,7 +156,7 @@ export declare class PmClient {
     /** Return project tracker statistics with the same sections as `pm stats`. */
     stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options): ReadPromise<StatsResult, Options>;
     /** Discover existing duplicate clusters without mutating tracker state. */
-    duplicates(options?: DuplicatesCommandOptions): Promise<DuplicatesResult>;
+    duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options): ReadPromise<DuplicatesResult, Options>;
     /** List, add, edit, or delete item comments. */
     comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options): ReadPromise<CommentsResult, Options>;
     /** List or append private item notes. */
@@ -371,7 +372,7 @@ export declare function aggregate<Options extends ReadOptions<AggregateOptions>
 /** Return project tracker statistics with the same sections as `pm stats` without constructing a reusable client. */
 export declare function stats<Options extends ReadOptions<StatsCommandOptions> = StatsCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<StatsResult, Options>;
 /** Discover duplicate clusters without constructing a reusable client. */
-export declare function duplicates(options?: DuplicatesCommandOptions, clientOptions?: PmClientOptions): Promise<DuplicatesResult>;
+export declare function duplicates<Options extends ReadOptions<DuplicatesCommandOptions> = DuplicatesCommandOptions>(options?: Options, clientOptions?: PmClientOptions): ReadPromise<DuplicatesResult, Options>;
 /** List, add, edit, or delete item comments without constructing a reusable client. */
 export declare function comments<Options extends ReadOptions<CommentsCommandOptions> = CommentsCommandOptions>(id: string, options?: Options, clientOptions?: PmClientOptions): ReadPromise<CommentsResult, Options>;
 /** List or append private item notes without constructing a reusable client. */

package/dist/sdk/runtime.js

@@ -4,9 +4,10 @@
  * Defines public SDK APIs and package-author helpers for Runtime.
  */
 
-!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]="c770afea-3eb6-5476-ba07-8ec1c5d9c699")}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]="a27b9b88-a8de-5e38-ab7f-dfcc61d1fad6")}catch(e){}}();
 export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, } from "./workspace.js";
 export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
+export * from "./cli-contracts/agent-output-contracts.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import path from "node:path";
 import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
@@ -1944,4 +1945,4 @@ async function loadWorkspaceExtensionRegistrations(pmRoot, settings, cwd) {
     }
 }
 //# sourceMappingURL=runtime.js.map
-//# debugId=c770afea-3eb6-5476-ba07-8ec1c5d9c699
+//# debugId=a27b9b88-a8de-5e38-ab7f-dfcc61d1fad6

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]="bb2758a5-a5c1-5f6e-be42-0e173fe16fe3")}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";
@@ -245,7 +245,7 @@ const runTestAllItem = async (entry, context) => {
     });
     const summary = countStatuses(runResults);
     const failureCategories = countFailureCategories(runResults);
-    const trackingWarnings = await appendTestAllItemTracking(entry, summary, context);
+    const trackingWarnings = await appendTestAllItemTracking(entry, summary, runResults, context);
     return {
         passed: summary.passed,
         failed: summary.failed,
@@ -273,7 +273,7 @@ const trackedRunFailed = (summary, options) => [
 ].includes(true);
 /** Projects true flags while keeping false values absent from persisted rows. */
 const optionalTrue = (value) => value ? true : undefined;
-const appendTestAllItemTracking = async (entry, summary, context) => {
+const appendTestAllItemTracking = async (entry, summary, runResults, context) => {
     if (!context.trackingEnabled) {
         return [];
     }
@@ -300,6 +300,14 @@ const appendTestAllItemTracking = async (entry, summary, context) => {
                 items: 1,
                 linked_tests: entry.tests.length,
                 fail_on_skipped_triggered: optionalTrue(context.options.failOnSkipped === true && summary.skipped > 0),
+                executions: runResults
+                    .filter((result) => result.command?.trim())
+                    .slice(0, 32)
+                    .map((result) => ({
+                    command: result.command.trim(),
+                    requested_pm_context_mode: result.execution_context?.requested_pm_context_mode,
+                    pm_context_mode: result.execution_context?.pm_context_mode,
+                })),
             },
         });
     }
@@ -421,9 +429,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 +495,4 @@ export const _testOnlyTestAll = {
     formatTrackingError,
 };
 //# sourceMappingURL=batch.js.map
-//# debugId=7fea0ecb-35e2-5d40-931f-ffdd1a465fdc
+//# debugId=bb2758a5-a5c1-5f6e-be42-0e173fe16fe3

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]="5fe0ee3e-9590-56fc-b238-e56ff1970e52")}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";
@@ -1790,6 +1791,14 @@ function buildTrackedTestRunSummary(params) {
         skipped: summary.skipped,
         fail_on_skipped_triggered: params.failOnSkippedTriggered ? true : undefined,
         measurements: measurements.length > 0 ? measurements : undefined,
+        executions: params.runResults
+            .filter((result) => result.command?.trim())
+            .slice(0, 32)
+            .map((result) => ({
+            command: result.command.trim(),
+            requested_pm_context_mode: result.execution_context?.requested_pm_context_mode,
+            pm_context_mode: result.execution_context?.pm_context_mode,
+        })),
     };
 }
 async function recordTestRunSummary(params) {
@@ -1849,9 +1858,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 +1972,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=4322c352-6b95-5796-94eb-5a68745d53bc
+//# debugId=5fe0ee3e-9590-56fc-b238-e56ff1970e52

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/dist/types.d.ts

@@ -558,6 +558,15 @@ export interface TestRunMeasurement {
     /** ISO 8601 timestamp binding the measurement to its producing run. */
     recorded_at: string;
 }
+/** Bounded command and tracker-context provenance for one linked-test execution. */
+export interface ItemTestRunExecution {
+    /** Exact linked command selected for execution. */
+    command: string;
+    /** Context mode requested before linked-test overrides or auto-remediation. */
+    requested_pm_context_mode?: "schema" | "tracker" | "auto";
+    /** Effective context mode used by the linked command. */
+    pm_context_mode?: "schema" | "tracker" | "auto";
+}
 /** Documents the item test run summary payload exchanged by command, SDK, and package integrations. */
 export interface ItemTestRunSummary {
     /** Executes the id operation through the package runtime. */
@@ -590,6 +599,8 @@ export interface ItemTestRunSummary {
     fail_on_skipped_triggered?: boolean;
     /** Bounded, deterministic quantitative evidence produced by this run. */
     measurements?: TestRunMeasurement[];
+    /** Commands and effective tracker contexts bound to this recorded run. */
+    executions?: ItemTestRunExecution[];
 }
 /** Documents the item metadata payload exchanged by command, SDK, and package integrations. */
 export interface ItemMetadata {

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** Supported values accepted by the builtin item type contract. */
 
-!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]="f6ab5bae-53b3-5feb-b89f-46e64afe7058")}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]="13c65470-8f5f-59ca-acb5-50c926c68870")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -243,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=f6ab5bae-53b3-5feb-b89f-46e64afe7058
+//# debugId=13c65470-8f5f-59ca-acb5-50c926c68870

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), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.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,29 @@ 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
+rows can be retired by selecting `id`, `kind` (or its input-only `type` alias),
+`source_kind`, `author`, and `created_at`; omitted coordinates intentionally broaden the match. Exact
+duplicate rows can still be normalized without delete-then-add risk by
+re-adding the same identity; the mutation keeps one canonical row and never
+removes the logical edge. Identity comparison includes normalized `id`, `kind`,
+`source_kind`, `author`, and creation instant, preserving provenance-distinct
+siblings.
+
+Hierarchy mutations are stricter than ordering advisories. `pm create` and
+`pm update` refuse a new cycle, registry cardinality breach, or contradictory
+scalar/dependency parent before writing. The structured refusal names the
+changed holder plus the cycle members or competing parents. Existing legacy
+debt remains mutable only toward a cleaner state, so repair does not require a
+global bypass. Read paths canonicalize every registry-declared hierarchy kind;
+an item cannot disappear from `pm list --parent` or `pm get --tree` merely
+because an integration used a dependency row instead of the scalar field.
+`pm update-many` applies the same hierarchy guard independently to each matched
+item: one refused row is reported as failed while other rows may still commit,
+so a bulk hierarchy mutation is not atomic across the complete match set.
+
 `pm graph audit` uses two explicit units:
 
 - `finding_count`, `findings_by_severity`, and `findings_by_code` count finding rows.