@unbrained/pm-cli 2026.8.16 → 2026.8.17

package/dist/sdk/relationship-analytics.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]="3a33af50-3d2c-57bb-884a-4d5394599ba2")}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]="3167c288-0bcc-5a66-8aa0-ca5876ed7d36")}catch(e){}}();
 import { createQueryFingerprint, decodeQueryCursor, encodeQueryCursor, } from "./pagination.js";
 import { createRelationshipKindRegistry, } from "./relationships.js";
 function visitImpactNeighbor(state, id, parent, root, after, limit) {
@@ -216,12 +216,80 @@ export function analyzeRelationshipExecution(graph, options = {}) {
         provenance: { algorithm: "kahn-longest-path", edgeFamily: "ordering" },
     };
 }
-/** Compute bounded impact rows and exact shortest explanation paths. */
-export function analyzeGraphImpact(graph, root, options = {}) {
-    const direction = options.direction ?? "outgoing";
+/** Build impact-only adjacency from stored source-to-target orientation. */
+function buildImpactAdjacency(graph, direction, kinds) {
+    const adjacency = createAdjacency(graph.nodes());
+    const selectedKinds = kinds === undefined
+        ? undefined
+        : new Set(kinds.map((kind) => graph.registry().require(kind).kind));
+    const edges = graph.edges();
+    for (const edge of edges) {
+        const definition = graph.registry().require(edge.kind);
+        if (selectedKinds !== undefined &&
+            !selectedKinds.has(edge.kind) &&
+            (definition.inverse === undefined ||
+                !selectedKinds.has(definition.inverse))) {
+            continue;
+        }
+        appendNeighbor(adjacency, direction === "incoming" ? edge.target : edge.source, direction === "incoming" ? edge.source : edge.target);
+    }
+    return { adjacency, inspectedEdges: edges.length };
+}
+/** Combine complete direction-locked incoming and outgoing impact traversals. */
+function analyzeBidirectionalGraphImpact(graph, root, options, after, limit, cursorFingerprint) {
+    const incoming = analyzeGraphImpact(graph, root, {
+        ...options,
+        after: undefined,
+        direction: "incoming",
+        limit: undefined,
+    });
+    const outgoing = analyzeGraphImpact(graph, root, {
+        ...options,
+        after: undefined,
+        direction: "outgoing",
+        limit: undefined,
+    });
+    const rows = new Map();
+    const candidates = [...incoming.affected, ...outgoing.affected].sort((left, right) => left.distance - right.distance ||
+        left.id.localeCompare(right.id) ||
+        left.path.join("\u0000").localeCompare(right.path.join("\u0000")));
+    for (const row of candidates) {
+        if (!rows.has(row.id)) {
+            rows.set(row.id, row);
+        }
+    }
+    const ordered = [...rows.values()].sort((left, right) => left.distance - right.distance || left.id.localeCompare(right.id));
+    const afterIndex = after === undefined || after === root
+        ? -1
+        : ordered.findIndex((row) => row.id === after);
+    if (after !== undefined && after !== root && afterIndex < 0) {
+        throw new TypeError(`Unknown impact cursor item: ${after}`);
+    }
+    const affected = ordered.slice(afterIndex + 1, afterIndex + 1 + limit);
+    const rowLimitTruncated = afterIndex + 1 + affected.length < ordered.length;
+    return {
+        root,
+        affected,
+        exact: true,
+        truncated: incoming.truncated || outgoing.truncated || rowLimitTruncated,
+        ...(rowLimitTruncated
+            ? {
+                nextCursor: encodeQueryCursor(cursorFingerprint, affected.at(-1)?.id ?? root),
+            }
+            : {}),
+        cost: {
+            visitedNodes: incoming.cost.visitedNodes + outgoing.cost.visitedNodes,
+            inspectedEdges: incoming.cost.inspectedEdges + outgoing.cost.inspectedEdges,
+        },
+    };
+}
+/** Compute one stored-direction impact traversal and exact shortest explanation paths. */
+function analyzeUnidirectionalGraphImpact(graph, root, options) {
+    const direction = options.direction;
     const maxDepth = options.maxDepth ?? Number.POSITIVE_INFINITY;
     const limit = options.limit ?? Number.POSITIVE_INFINITY;
     const { fingerprint: cursorFingerprint, after } = resolveImpactCursor(root, options, direction, maxDepth);
+    const { adjacency, inspectedEdges } = buildImpactAdjacency(graph, direction, options.kinds);
     const state = {
         queue: [{ id: root, depth: 0 }],
         seen: new Set([root]),
@@ -230,25 +298,19 @@ export function analyzeGraphImpact(graph, root, options = {}) {
         cursorFound: after === undefined || after === root,
     };
     let visitedNodes = 0;
-    let inspectedEdges = 0;
     let truncated = false;
     let rowLimitTruncated = false;
     traversal: for (let index = 0; index < state.queue.length; index += 1) {
         options.signal?.throwIfAborted();
         const current = state.queue[index];
         visitedNodes += 1;
-        const adjacent = graph.adjacency(current.id, {
-            direction,
-            kinds: options.kinds,
-            signal: options.signal,
-        });
-        inspectedEdges += adjacent.meta.inspectedEdges;
+        const adjacent = [...adjacency.get(current.id)].sort();
         if (current.depth >= maxDepth) {
-            if (adjacent.value.some((id) => !state.seen.has(id)))
+            if (adjacent.some((id) => !state.seen.has(id)))
                 truncated = true;
             continue;
         }
-        for (const id of adjacent.value) {
+        for (const id of adjacent) {
             const outcome = visitImpactNeighbor(state, id, current, root, after, limit);
             if (outcome === "truncate") {
                 truncated = true;
@@ -273,6 +335,20 @@ export function analyzeGraphImpact(graph, root, options = {}) {
         cost: { visitedNodes, inspectedEdges },
     };
 }
+/** Compute bounded impact rows and exact shortest explanation paths. */
+export function analyzeGraphImpact(graph, root, options = {}) {
+    const direction = options.direction ?? "outgoing";
+    if (direction !== "both") {
+        return analyzeUnidirectionalGraphImpact(graph, root, {
+            ...options,
+            direction,
+        });
+    }
+    const maxDepth = options.maxDepth ?? Number.POSITIVE_INFINITY;
+    const limit = options.limit ?? Number.POSITIVE_INFINITY;
+    const { fingerprint, after } = resolveImpactCursor(root, options, direction, maxDepth);
+    return analyzeBidirectionalGraphImpact(graph, root, options, after, limit, fingerprint);
+}
 /** Analyze weak/strong components, isolates, and exact unique-neighbor hubs. */
 export function analyzeKnowledgeGraph(graph) {
     const nodes = [...graph.nodes()];
@@ -332,4 +408,4 @@ export function compareRelationshipSnapshots(before, after) {
     };
 }
 //# sourceMappingURL=relationship-analytics.js.map
-//# debugId=3a33af50-3d2c-57bb-884a-4d5394599ba2
+//# debugId=3167c288-0bcc-5a66-8aa0-ca5876ed7d36

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

@@ -9,6 +9,8 @@ export type RelationshipDirection = "directed" | "undirected";
 export type RelationshipCardinality = "one" | "many";
 /** Lifecycle policy for a relationship kind. */
 export type RelationshipLifecycle = "persistent" | "supersedable" | "ephemeral";
+/** Temporal meaning carried by a directed relationship independently of execution precedence. */
+export type RelationshipTemporalOrder = "source_after_target";
 /** Direction in which an ordering edge contributes to execution precedence. */
 export type RelationshipPrecedence = "source_before_target" | "target_before_source";
 /** Endpoint that represents the structural parent for hierarchy kinds. */
@@ -23,6 +25,8 @@ export interface RelationshipKindDefinition {
     inverse?: string;
     /** Whether the kind participates in execution-order cycle checks. */
     ordering: boolean;
+    /** Optional chronological constraint; recurrence uses source-after-target without becoming scheduling precedence. */
+    temporalOrder?: RelationshipTemporalOrder;
     /** Execution direction for ordering kinds; defaults to source before target. */
     precedence?: RelationshipPrecedence;
     /** Whether the kind contributes to structural ancestry. */

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

@@ -5,7 +5,7 @@
  */
 /** 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]="49a83ce3-4c55-5b3f-b061-bc21b716d498")}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]="825e1dd9-4168-56f6-9183-b8cf75314b73")}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 },
@@ -15,8 +15,9 @@ export const BUILTIN_RELATIONSHIP_KINDS = [
     { 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 },
 ];
 //# sourceMappingURL=contract.js.map
-//# debugId=49a83ce3-4c55-5b3f-b061-bc21b716d498
+//# debugId=825e1dd9-4168-56f6-9183-b8cf75314b73

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, } 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";
 /** 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]="05e01593-acb6-5e28-a5ac-8c8f74359c62")}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]="7f733de4-104b-50a9-9c0a-cd9850bfcd78")}catch(e){}}();
 import { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 export { BUILTIN_RELATIONSHIP_KINDS, } from "./relationship-kinds/contract.js";
 function normalizeKind(kind) {
@@ -36,6 +36,14 @@ function assertRelationshipPrecedence(definition, kind) {
     if (!definition.ordering && definition.precedence !== undefined)
         throw new TypeError(`Non-ordering relationship kind cannot declare precedence: ${kind}`);
 }
+function assertRelationshipTemporalOrder(definition, kind) {
+    if (definition.temporalOrder !== undefined &&
+        definition.temporalOrder !== "source_after_target")
+        throw new TypeError(`Invalid relationship temporal order for ${kind}`);
+    if (definition.direction !== "directed" &&
+        definition.temporalOrder !== undefined)
+        throw new TypeError(`Undirected relationship kind cannot declare temporal order: ${kind}`);
+}
 function assertRelationshipHierarchyDirection(definition, kind) {
     if (definition.hierarchyDirection !== undefined &&
         definition.hierarchyDirection !== "source_parent" &&
@@ -102,6 +110,7 @@ export class RelationshipKindRegistry {
         assertRelationshipKindSemantics(definition, kind);
         assertRelationshipKindPayload(definition, kind);
         assertRelationshipPrecedence(definition, kind);
+        assertRelationshipTemporalOrder(definition, kind);
         assertRelationshipHierarchyDirection(definition, kind);
         if (this.#definitions.has(kind) || this.#aliases.has(kind))
             throw new TypeError(`Relationship kind already registered: ${kind}`);
@@ -543,4 +552,4 @@ export function dependencyToRelationship(source, dependency, registry = defaultR
     };
 }
 //# sourceMappingURL=relationships.js.map
-//# debugId=05e01593-acb6-5e28-a5ac-8c8f74359c62
+//# debugId=7f733de4-104b-50a9-9c0a-cd9850bfcd78

package/dist/sdk/schema.d.ts

@@ -500,6 +500,7 @@ export declare function formatSchemaApplyPresetHuman(result: SchemaApplyPresetRe
 export declare function formatSchemaInferTypesHuman(result: SchemaAddTypeInferResult): string;
 /** Re-export so register-mutation can surface the hint in usage examples without importing the core module directly. */
 export { buildInvalidTypeHint };
+export type { RuntimeFieldDefinition, RuntimeFieldValueSchema, } from "../core/schema/fields-file.js";
 /** Public contract for test only schema command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlySchemaCommand: {
     workflowSlotsReferencing: typeof workflowSlotsReferencing;

package/dist/sdk/schema.js

@@ -4,7 +4,7 @@
  * 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]="1a035e10-b8fe-52cd-a9c7-0762dd0ab160")}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]="2ab8a5a9-dbea-526f-a541-b7ca2b106ac5")}catch(e){}}();
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { resolveAuthor } from "../core/shared/author.js";
@@ -1365,4 +1365,4 @@ export const _testOnlySchemaCommand = {
     workflowSlotsReferencing,
 };
 //# sourceMappingURL=schema.js.map
-//# debugId=1a035e10-b8fe-52cd-a9c7-0762dd0ab160
+//# debugId=2ab8a5a9-dbea-526f-a541-b7ca2b106ac5

package/dist/sdk/test/execution.d.ts

@@ -201,7 +201,9 @@ declare function formatLinkedTestExecutionError(result: LinkedTestExecutionResul
 export declare function classifyLinkedTestFailure(result: Pick<LinkedTestExecutionResult, "stdout" | "stderr" | "spawnError" | "signal" | "timedOut" | "maxBufferExceeded">): LinkedTestFailureCategory;
 /** Implements count failure categories for the public runtime surface of this module. */
 export declare function countFailureCategories(runResults: TestRunResult[]): Record<LinkedTestFailureCategory, number>;
-declare function copyIntoSandboxIfPresent(sourcePath: string, targetPath: string, recursive?: boolean): Promise<void>;
+declare function copyIntoSandboxIfPresent(sourcePath: string, targetPath: string, recursive?: boolean, makeDirectory?: (targetPath: string, options: {
+    recursive: true;
+}) => Promise<unknown>): Promise<void>;
 declare function seedLinkedTestSandbox(sandboxPmPath: string, sandboxGlobalPath: string, sourceRoots: LinkedTestSandboxSourceRoots): Promise<void>;
 declare function seedLinkedTestTrackerData(sourceRoot: string, sandboxRoot: string): Promise<void>;
 declare function countLinkedTestItemFiles(pmRoot: string): Promise<number>;
@@ -242,7 +244,8 @@ interface LinkedTestSandboxCounts {
     trackerProjectItemCount: number;
     trackerGlobalItemCount: number;
 }
-declare function initializeLinkedTestSandboxes(layout: LinkedTestSandboxLayout, initialize?: (...args: Parameters<typeof runInit>) => Promise<unknown>): Promise<void>;
+declare function initializeLinkedTestSandboxes(layout: LinkedTestSandboxLayout, initialize?: (...args: Parameters<typeof runInit>) => Promise<unknown>, includeTrackerData?: boolean): Promise<void>;
+declare function linkedTestsRequireTrackerData(tests: LinkedTest[], runLevelPmContextMode: LinkedTestPmContextMode, options: RunLinkedTestsOptions | undefined): boolean;
 declare function buildLinkedTestExecutionContext(params: {
     layout: LinkedTestSandboxLayout;
     counts: LinkedTestSandboxCounts;
@@ -280,6 +283,7 @@ export declare const _testOnlyTestCommand: {
     formatLinkedTestExecutionError: typeof formatLinkedTestExecutionError;
     hasLinkedTestAssertions: typeof hasLinkedTestAssertions;
     initializeLinkedTestSandboxes: typeof initializeLinkedTestSandboxes;
+    linkedTestsRequireTrackerData: typeof linkedTestsRequireTrackerData;
     parseAddJsonEntries: typeof parseAddJsonEntries;
     parseLinkedTestTimeoutSeconds: typeof parseLinkedTestTimeoutSeconds;
     parsePmContextMode: typeof parsePmContextMode;

package/dist/sdk/test/execution.js

@@ -4,7 +4,7 @@
  * 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]="76053150-cc55-57e0-80d6-369196284cd0")}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]="4322c352-6b95-5796-94eb-5a68745d53bc")}catch(e){}}();
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, open, readdir, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -28,6 +28,7 @@ import { LINKED_TEST_PM_CONTEXT_MODE_VALUES as PM_CONTEXT_MODE_VALUES, LINKED_TE
 import { parseOnlyIndexValue, resolveLinkedTestRunSelection, } from "../../core/test/run-selectors.js";
 import { SCOPE_VALUES } from "../../types/index.js";
 import { diffTestRunMeasurements, parseTestRunMeasurements, queryTestRunMeasurementsBelow, } from "./measurements.js";
+import { withHostEnvironmentBoundary } from "../environment/host-environment-errors.js";
 import { SOURCE_CONTEXT_ACCESS_ENV } from "../environment/source-context.js";
 const TEST_OUTPUT_MAX_BUFFER_BYTES = 20 * 1024 * 1024;
 const DEFAULT_LINKED_TEST_TIMEOUT_FORCE_KILL_DELAY_MS = 3000;
@@ -973,17 +974,24 @@ function resolveRuntimeDirectives(envSetEntries, envClearEntries, sharedHostSafe
     };
 }
 /* c8 ignore start -- sandbox copy race/path permutations are covered by filesystem integration suites */
-async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = false) {
+async function copyIntoSandboxIfPresent(sourcePath, targetPath, recursive = false, makeDirectory = mkdir) {
     if (!(await pathExists(sourcePath))) {
         return;
     }
-    await mkdir(path.dirname(targetPath), { recursive: true });
     try {
-        if (recursive) {
-            await cp(sourcePath, targetPath, { recursive: true, force: true });
-            return;
-        }
-        await cp(sourcePath, targetPath, { force: true });
+        await withHostEnvironmentBoundary("seed_linked_test", async () => {
+            await makeDirectory(path.dirname(targetPath), { recursive: true });
+            if (recursive) {
+                await cp(sourcePath, targetPath, { recursive: true, force: true });
+                return;
+            }
+            await cp(sourcePath, targetPath, { force: true });
+        }, {
+            why: "Linked tests need an isolated PM context without mutating the source tracker.",
+            nextSteps: [
+                "Reclaim capacity on the filesystem that hosts the linked-test temporary directory.",
+            ],
+        });
     }
     catch (error) {
         if (typeof error === "object" &&
@@ -1257,22 +1265,38 @@ function createLinkedTestSandboxLayout(sandboxRoot) {
         trackerGlobalPmPath: path.join(sandboxRoot, "tracker", "global"),
     };
 }
-async function initializeLinkedTestSandboxes(layout, initialize = runInit) {
+async function initializeLinkedTestSandboxes(layout, initialize = runInit, includeTrackerData = true) {
     const initOptions = { defaults: true, agentGuidance: "skip" };
     await initialize(undefined, { path: layout.schemaProjectPmPath }, initOptions);
     await initialize(undefined, { path: layout.schemaGlobalPmPath }, initOptions);
+    if (!includeTrackerData) {
+        return;
+    }
     await initialize(undefined, { path: layout.trackerProjectPmPath }, initOptions);
     await initialize(undefined, { path: layout.trackerGlobalPmPath }, initOptions);
 }
-async function seedLinkedTestSandboxesFromSource(layout, sourceRoots) {
+async function seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTrackerData) {
     if (!sourceRoots) {
         return;
     }
     await seedLinkedTestSandbox(layout.schemaProjectPmPath, layout.schemaGlobalPmPath, sourceRoots);
+    if (!includeTrackerData) {
+        return;
+    }
     await seedLinkedTestSandbox(layout.trackerProjectPmPath, layout.trackerGlobalPmPath, sourceRoots);
     await seedLinkedTestTrackerData(sourceRoots.projectPmRoot, layout.trackerProjectPmPath);
     await seedLinkedTestTrackerData(sourceRoots.globalPmRoot, layout.trackerGlobalPmPath);
 }
+function linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options) {
+    return tests.some((linkedTest) => {
+        const command = linkedTest.command ?? "";
+        const isPmTrackerReadCommand = command.length > 0 && commandInvokesPmTrackerReadCommand(command);
+        const requestedPmContextMode = options?.autoPmContext === true && isPmTrackerReadCommand
+            ? "auto"
+            : resolveLinkedTestRequestedContextMode(linkedTest, runLevelPmContextMode, options?.overrideLinkedPmContext === true);
+        return (resolveLinkedTestEffectiveContextMode(requestedPmContextMode, isPmTrackerReadCommand) === "tracker");
+    });
+}
 async function countLinkedTestSandboxItems(layout, sourceRoots) {
     return {
         sourceProjectItemCount: sourceRoots
@@ -1510,9 +1534,10 @@ export async function runLinkedTests(tests, defaultTimeoutSeconds, options) {
     const progressMode = options?.progress === true ? "always" : "auto";
     const runtimeDirectives = resolveRuntimeDirectives(options?.envSet, options?.envClear, options?.sharedHostSafe);
     const sourceRoots = options?.sourceRoots;
+    const includeTrackerData = linkedTestsRequireTrackerData(tests, runLevelPmContextMode, options);
     try {
-        await initializeLinkedTestSandboxes(layout);
-        await seedLinkedTestSandboxesFromSource(layout, sourceRoots);
+        await initializeLinkedTestSandboxes(layout, runInit, includeTrackerData);
+        await seedLinkedTestSandboxesFromSource(layout, sourceRoots, includeTrackerData);
         const counts = await countLinkedTestSandboxItems(layout, sourceRoots);
         for (let index = 0; index < tests.length; index += 1) {
             const linkedTest = tests[index];
@@ -1920,6 +1945,7 @@ export const _testOnlyTestCommand = {
     formatLinkedTestExecutionError,
     hasLinkedTestAssertions,
     initializeLinkedTestSandboxes,
+    linkedTestsRequireTrackerData,
     parseAddJsonEntries,
     parseLinkedTestTimeoutSeconds,
     parsePmContextMode,
@@ -1939,4 +1965,4 @@ export const _testOnlyTestCommand = {
     summarizeRunResultStatuses,
 };
 //# sourceMappingURL=execution.js.map
-//# debugId=76053150-cc55-57e0-80d6-369196284cd0
+//# debugId=4322c352-6b95-5796-94eb-5a68745d53bc

package/dist/types.d.ts

@@ -32,7 +32,7 @@ export declare const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES: readonly ["allow", "wa
 /** Restricts runtime unknown field policy values accepted by command, SDK, and storage contracts. */
 export type RuntimeUnknownFieldPolicy = (typeof RUNTIME_UNKNOWN_FIELD_POLICY_VALUES)[number];
 /** Supported values accepted by the dependency kind contract. */
-export declare const DEPENDENCY_KIND_VALUES: readonly ["blocks", "parent", "child", "parent_child", "child_of", "related", "related_to", "discovered_from", "blocked_by", "incident_from", "epic", "implements", "supersedes", "task", "verifies"];
+export declare const DEPENDENCY_KIND_VALUES: readonly ["blocks", "parent", "child", "parent_child", "child_of", "related", "related_to", "discovered_from", "blocked_by", "incident_from", "epic", "implements", "recurs_from", "supersedes", "task", "verifies"];
 /** Restricts dependency kind values accepted by command, SDK, and storage contracts. */
 export type DependencyKind = (typeof DEPENDENCY_KIND_VALUES)[number];
 /** Supported values accepted by the scope contract. */
@@ -266,7 +266,7 @@ export declare const PLAN_HARNESS_VALUES: readonly ["codex", "claude-code", "cur
 /** Restricts plan harness values accepted by command, SDK, and storage contracts. */
 export type PlanHarness = (typeof PLAN_HARNESS_VALUES)[number];
 /** Supported values accepted by the plan step link kind contract. */
-export declare const PLAN_STEP_LINK_KIND_VALUES: readonly ["related", "blocks", "blocked_by", "depends_on", "discovered_from", "implements", "verifies", "supersedes"];
+export declare const PLAN_STEP_LINK_KIND_VALUES: readonly ["related", "blocks", "blocked_by", "depends_on", "discovered_from", "implements", "recurs_from", "verifies", "supersedes"];
 /** Restricts plan step link kind values accepted by command, SDK, and storage contracts. */
 export type PlanStepLinkKind = (typeof PLAN_STEP_LINK_KIND_VALUES)[number];
 /** Documents the plan step link payload exchanged by command, SDK, and package integrations. */
@@ -437,6 +437,31 @@ export interface RuntimeStatusDefinition {
     /** Value that configures or reports order for this contract. */
     order?: number;
 }
+/** Declarative JSON-value constraints enforced before custom-field persistence. */
+export interface RuntimeFieldValueSchema {
+    /** Optional JSON value type constraint. */
+    type?: "string" | "number" | "boolean" | "array" | "object";
+    /** Exact JSON value required by this schema branch. */
+    const?: StructuredJsonValue;
+    /** Complete allowed JSON value set. */
+    enum?: StructuredJsonValue[];
+    /** Minimum accepted string length. */
+    min_length?: number;
+    /** Minimum accepted array length. */
+    min_items?: number;
+    /** Optional semantic string format. */
+    format?: "date-time";
+    /** Object-property schemas keyed by the persisted property name. */
+    properties?: Record<string, RuntimeFieldValueSchema>;
+    /** Object properties that must be present. */
+    required?: string[];
+    /** Whether properties absent from `properties` are accepted. */
+    additional_properties?: boolean;
+    /** Schema applied to every array element. */
+    items?: RuntimeFieldValueSchema;
+    /** Alternative schemas of which exactly one must match. */
+    one_of?: RuntimeFieldValueSchema[];
+}
 /** Documents the runtime field definition payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeFieldDefinition {
     /** Value that configures or reports key for this contract. */
@@ -467,6 +492,8 @@ export interface RuntimeFieldDefinition {
     required_types?: string[];
     /** Value that configures or reports allow unset for this contract. */
     allow_unset?: boolean;
+    /** Optional semantic JSON-value constraints enforced on create and update. */
+    value_schema?: RuntimeFieldValueSchema;
 }
 /** Documents the runtime workflow definition payload exchanged by command, SDK, and package integrations. */
 export interface RuntimeWorkflowDefinition {

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]="8b39bc01-0325-5dc6-8492-585c98608076")}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]="4e2028b3-6718-509a-b687-d1df58962387")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -81,6 +81,7 @@ export const DEPENDENCY_KIND_VALUES = [
     "incident_from",
     "epic",
     "implements",
+    "recurs_from",
     "supersedes",
     "task",
     "verifies",
@@ -217,6 +218,7 @@ export const PLAN_STEP_LINK_KIND_VALUES = [
     "depends_on",
     "discovered_from",
     "implements",
+    "recurs_from",
     "verifies",
     "supersedes",
 ];
@@ -241,4 +243,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=8b39bc01-0325-5dc6-8492-585c98608076
+//# debugId=4e2028b3-6718-509a-b687-d1df58962387

package/docs/CONFIGURATION.md

@@ -156,7 +156,7 @@ Telemetry is opt-in via `pm config set telemetry-tracking on` (see [Common Setti
 | `PM_TELEMETRY_OTEL_DISABLED`         | boolean                                       | Disable only OTLP trace-span export; the event queue still flushes.                                                                             |
 | `PM_TELEMETRY_INLINE_FLUSH`          | boolean                                       | Flush the queue and OTLP spans inline instead of dispatching the detached worker. Mainly for tests; normal use relies on the background worker. |
 | `PM_TELEMETRY_SOURCE_CONTEXT`        | `user` \| `automation` \| `test` \| `dogfood` | Override the inferred source context recorded on each event. Any other value is ignored and the context is inferred.                            |
-| `PM_TELEMETRY_HTTP_TIMEOUT_MS`        | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
+| `PM_TELEMETRY_HTTP_TIMEOUT_MS`       | integer milliseconds                          | Bound each background event or OTLP request (default `20000`, clamped to `1000`–`25000` to stay below the worker lock TTL).                     |
 | `PM_TELEMETRY_INGEST_KEY`            | string                                        | Sent as the `x-pm-telemetry-key` header on queue flushes; never logged.                                                                         |
 | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | URL                                           | OTLP/HTTP traces endpoint for command spans. Takes precedence over the base endpoint.                                                           |
 | `OTEL_EXPORTER_OTLP_ENDPOINT`        | URL                                           | Base OTLP endpoint; the traces endpoint is derived by appending `/v1/traces`.                                                                   |
@@ -523,6 +523,11 @@ Fields live in `.agents/pm/schema/fields.json` with the shape `{ "fields": [Runt
       "required_on_create": false, // required only on create
       "allow_unset": true, // allow clearing via --component "" / --no-component
       "required_types": ["Task"], // only required for these item types (subset of required*)
+      "value_schema": {
+        // optional recursive semantic constraints
+        "type": "string",
+        "enum": ["frontend", "backend", "operations"],
+      },
     },
   ],
 }
@@ -541,6 +546,7 @@ Fields live in `.agents/pm/schema/fields.json` with the shape `{ "fields": [Runt
 - `allow_unset` — when `true` (default), the field can be cleared; when `false`, an explicit unset is rejected.
 - `required_types` — narrows `required`/`required_on_create` to only the listed item types.
 - `description` — surfaced in `--help`.
+- `value_schema` — optional recursive JSON-value validation applied after CLI coercion and before create/update persistence. It supports `type`, `const`, `enum`, `min_length`, `min_items`, `format: "date-time"`, object `properties`/`required`/`additional_properties`, array `items`, and exact-one `one_of` variants. This lets project-defined fields enforce domain semantics without custom command code.
 
 End-to-end example — add a required-on-create `component` string field on `Task` items:
 
@@ -561,6 +567,57 @@ End-to-end example — add a required-on-create `component` string field on `Tas
 }
 ```
 
+Object schemas can model discriminated evidence contracts. The following accepts either complete gate proof or an expiring waiver and rejects unknown keys:
+
+```jsonc
+{
+  "key": "gate_evidence",
+  "type": "object",
+  "value_schema": {
+    "type": "object",
+    "required": ["disposition", "owner"],
+    "additional_properties": false,
+    "properties": {
+      "disposition": {
+        "enum": ["gate_added", "gate_strengthened", "explicit_waiver"],
+      },
+      "owner": { "type": "string", "min_length": 1 },
+      "gate_id": { "type": "string", "min_length": 1 },
+      "negative_control": { "type": "string", "min_length": 1 },
+      "local_checks": {
+        "type": "array",
+        "min_items": 1,
+        "items": { "type": "string", "min_length": 1 },
+      },
+      "hosted_checks": {
+        "type": "array",
+        "min_items": 1,
+        "items": { "type": "string", "min_length": 1 },
+      },
+      "waiver_reason": { "type": "string", "min_length": 1 },
+      "waiver_expires_at": { "type": "string", "format": "date-time" },
+    },
+    "one_of": [
+      {
+        "properties": {
+          "disposition": { "enum": ["gate_added", "gate_strengthened"] },
+        },
+        "required": [
+          "gate_id",
+          "negative_control",
+          "local_checks",
+          "hosted_checks",
+        ],
+      },
+      {
+        "properties": { "disposition": { "const": "explicit_waiver" } },
+        "required": ["waiver_reason", "waiver_expires_at"],
+      },
+    ],
+  },
+}
+```
+
 ```bash
 pm create Task "Fix token refresh" --component auth   # stored in item metadata
 pm list --component auth                              # filter by the custom field